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);
import requests
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']]
{
"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"
}
Orders
Get Order Downloads
Retrieve all downloadable files for an order with pre-computed status flags.
GET
/
orders
/
{id}
/
downloads
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);
import requests
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']]
{
"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"
}
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.
Understanding the
The
Recommended client flow:
Path parameters
string
required
The order’s unique identifier (UUID).
Response
string
required
The order’s unique identifier.
string
required
The order name/number, e.g.
#1042.array
required
Flat list of download objects. Each object represents one file or licence key.
Show Download properties
Show Download properties
string
required
Unique identifier for this download entry (UUID).
string
required
Name of the product this file belongs to.
string
required
Name of the file, e.g.
artwork-collection.zip. For licence keys this is Licence Key.string
required
MIME type of the file, e.g.
application/pdf. For licence keys this is licence/key.integer
required
File size in bytes. Returns
0 for external links and licence keys.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.boolean
required
true if this file is personalised with the buyer’s details by your store’s PDF watermarking settings.string
required
One of
not_applicable, processing, or ready. See Watermarked files.integer
required
Number of times this file has been downloaded for this order.
integer | null
required
Maximum downloads allowed per file as configured in your store settings.
null means unlimited.boolean
required
true if download_count has reached or exceeded download_limit.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.boolean
required
true if the current time is past expires_at.boolean
required
true if access to this file has been revoked, e.g. due to a refund or cancellation.boolean
required
true if this file belongs to a preorder product.string | null
required
ISO 8601 timestamp of the preorder release date.
null for non-preorder items.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.boolean
required
true if this entry represents a licence key instead of a downloadable file.string | null
required
The licence key value if this is a licence key type and one has been assigned.
null otherwise.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 |
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. |
GET /orders/{id}/downloads.- 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. - Once
watermark_statusisready, downloaddownload_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.
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.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);
import requests
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']]
{
"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"
}