Get Order Downloads

Returns a flat list of every file associated with an order. Each item includes boolean flags that tell you exactly whether the file can be downloaded right now and why it might be unavailable. You do not need to implement any expiration, limit, or access-revocation logic on your end.

Path parameters

• id (string, path, required)

  The order’s unique identifier (UUID).

Response

• order_id (string, required)

  The order’s unique identifier.

• order_name (string, required)

  The order name/number, e.g. #1042.

• downloads (array, required)

  Flat list of download objects. Each object represents one file or licence key.

  Download properties:

  • id (string, required)

    Unique identifier for this download entry (UUID).

  • product_name (string, required)

    Name of the product this file belongs to.

  • file_name (string, required)

    Name of the file, e.g. artwork-collection.zip. For licence keys this is Licence Key.

  • file_type (string, required)

    MIME type of the file, e.g. application/pdf. For licence keys this is licence/key.

  • file_size_bytes (integer, required)

    File size in bytes. Returns 0 for external links and licence keys.

  • download_url (string | null, required)

    A signed download URL for internal files or the external URL for external files. null when downloadable is false, and also null while watermark_status is processing.

  • is_watermarked (boolean, required)

    true if this file is personalised with the buyer’s details by your store’s PDF watermarking settings.

  • watermark_status (string, required)

    One of not_applicable, processing, or ready. See Watermarked files.

  • download_count (integer, required)

    Number of times this file has been downloaded for this order.

  • download_limit (integer | null, required)

    Maximum downloads allowed per file as configured in your store settings. null means unlimited.

  • download_limit_reached (boolean, required)

    true if download_count has reached or exceeded download_limit.

  • expires_at (string | null, required)

    ISO 8601 timestamp of when the download expires, based on the order creation date plus your store’s download limit days setting. null if no expiration is configured.

  • download_expired (boolean, required)

    true if the current time is past expires_at.

  • access_revoked (boolean, required)

    true if access to this file has been revoked, e.g. due to a refund or cancellation.

  • is_preorder (boolean, required)

    true if this file belongs to a preorder product.

  • preorder_available_at (string | null, required)

    ISO 8601 timestamp of the preorder release date. null for non-preorder items.

  • preorder_released (boolean, required)

    true if the preorder has been released (or if the item is not a preorder). false if the release date is in the future.

  • is_licence_key (boolean, required)

    true if this entry represents a licence key instead of a downloadable file.

  • licence_key (string | null, required)

    The licence key value if this is a licence key type and one has been assigned. null otherwise.

  • downloadable (boolean, required)

    Master flag. true only when all of the following are met: download has not expired, download limit has not been reached, access has not been revoked, and the preorder has been released (if applicable).

Understanding the downloadable flag

The downloadable field is a convenience flag that combines all the individual status checks:

Condition	Field	downloadable is false when…
Time expiration	download_expired	The download window has passed
Count limit	download_limit_reached	The customer has used all their downloads
Access revoked	access_revoked	The order was refunded or cancelled
Preorder pending	preorder_released	The preorder hasn’t been released yet

Tip

If you only need to know whether a file is available, check the downloadable field. Use the individual flags when you need to display a specific reason to the user.

Watermarked files

When PDF watermarking is enabled in your store settings, eligible PDFs are stamped with the buyer’s details. Watermarking runs asynchronously and is generated on demand: calling this endpoint starts the job for any eligible file that does not have one yet, exactly like the customer opening the hosted download page.

watermark_status	is_watermarked	download_url
not_applicable	false	The raw file (or external URL). Watermarking is off, the file is not an eligible PDF, or watermarking is disabled for that file.
processing	true	null — the watermark is still being generated. Poll this endpoint again.
ready	true	A short-lived signed URL for the watermarked copy of the file.

Recommended client flow:

1. GET /orders/{id}/downloads.
2. For any entry with watermark_status: "processing", wait a few seconds and call the endpoint again. Watermarking typically completes within seconds; only the first request per file hits this window.
3. Once watermark_status is ready, download download_url. The returned PDF already contains the buyer’s name and email, so it stays watermarked when stored offline.

download_url is never the un-watermarked original, so a ready entry can come back with download_url: null in the rare case where the signed URL could not be generated. Treat that like processing and retry.

downloadable still gates everything: if it is false (expired, revoked, limit reached, or unreleased preorder) then download_url is null regardless of watermark status.

Note

Legacy files still stored on our previous storage provider cannot be served as a watermarked copy through the API and are returned as not_applicable.

Example request

curl -X GET 'https://app.filemonk.io/api/v1/external/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890/downloads' \
  -H 'X-Auth-Token: fm_api_key_your_key_here'

const orderId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const response = await fetch(
  `https://app.filemonk.io/api/v1/external/orders/${orderId}/downloads`,
  { headers: { 'X-Auth-Token': 'fm_api_key_your_key_here' } }
);
const data = await response.json();

const availableDownloads = data.downloads.filter(d => d.downloadable);

order_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
response = requests.get(
    f'https://app.filemonk.io/api/v1/external/orders/{order_id}/downloads',
    headers={'X-Auth-Token': 'fm_api_key_your_key_here'}
)
data = response.json()

available = [d for d in data['downloads'] if d['downloadable']]

Example response

{
  "order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "order_name": "#1042",
  "downloads": [
    {
      "id": "d1e2f3a4-b5c6-7890-def0-123456789abc",
      "product_name": "Digital Art Pack",
      "file_name": "artwork-collection.zip",
      "file_type": "application/zip",
      "file_size_bytes": 52428800,
      "download_url": "https://app.filemonk.io/rails/active_storage/blobs/redirect/signed-token/artwork-collection.zip",
      "is_watermarked": false,
      "watermark_status": "not_applicable",
      "download_count": 2,
      "download_limit": 5,
      "download_limit_reached": false,
      "expires_at": "2026-04-01T14:30:00Z",
      "download_expired": false,
      "access_revoked": false,
      "is_preorder": false,
      "preorder_available_at": null,
      "preorder_released": true,
      "is_licence_key": false,
      "licence_key": null,
      "downloadable": true
    },
    {
      "id": "e2f3a4b5-c6d7-8901-ef01-23456789abcd",
      "product_name": "Digital Art Pack",
      "file_name": "bonus-brushes.zip",
      "file_type": "application/zip",
      "file_size_bytes": 10485760,
      "download_url": null,
      "is_watermarked": false,
      "watermark_status": "not_applicable",
      "download_count": 5,
      "download_limit": 5,
      "download_limit_reached": true,
      "expires_at": "2026-04-01T14:30:00Z",
      "download_expired": false,
      "access_revoked": false,
      "is_preorder": false,
      "preorder_available_at": null,
      "preorder_released": true,
      "is_licence_key": false,
      "licence_key": null,
      "downloadable": false
    },
    {
      "id": "f3a4b5c6-d7e8-9012-f012-3456789abcde",
      "product_name": "Pro Software License",
      "file_name": "Licence Key",
      "file_type": "licence/key",
      "file_size_bytes": 0,
      "download_url": null,
      "is_watermarked": false,
      "watermark_status": "not_applicable",
      "download_count": 0,
      "download_limit": null,
      "download_limit_reached": false,
      "expires_at": null,
      "download_expired": false,
      "access_revoked": false,
      "is_preorder": false,
      "preorder_available_at": null,
      "preorder_released": true,
      "is_licence_key": true,
      "licence_key": "ABCD-1234-EFGH-5678",
      "downloadable": true
    },
    {
      "id": "a4b5c6d7-e8f9-0123-0123-456789abcdef",
      "product_name": "Design Handbook",
      "file_name": "design-handbook.pdf",
      "file_type": "application/pdf",
      "file_size_bytes": 8388608,
      "download_url": null,
      "is_watermarked": true,
      "watermark_status": "processing",
      "download_count": 0,
      "download_limit": 5,
      "download_limit_reached": false,
      "expires_at": "2026-04-01T14:30:00Z",
      "download_expired": false,
      "access_revoked": false,
      "is_preorder": false,
      "preorder_available_at": null,
      "preorder_released": true,
      "is_licence_key": false,
      "licence_key": null,
      "downloadable": true
    }
  ]
}

{
  "error": "Order not found"
}