comecerodocs
Downloads

Create a download

POST
/files/{file_id}/downloads

Makes a new download link to a file, for example to send a customer a file by hand. Comecero makes these on its own for each order item whose product has a file. The link's limits come from the file unless you send your own. The body is JSON and may be an empty object. The token needs the create permission on downloads. Secret and trusted tokens may call it.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

file_id*string

The file id.

Query Parameters

timezone?string

An IANA time zone name, such as America/New_York or UTC. It sets how date_start and date_end are read and the time zone of every date in the response. The default is the account's time zone (Settings, Technical), or UTC when it has none. A name that is not known is a 400.

expand?string

Comma-separated child objects to return in full instead of as a URL, for example customer,payments. Use dot notation for nested objects (items.product), up to four levels deep. A single object takes up to 12 paths; a list takes up to 2, applied to every item. Extra paths are dropped without an error. See Expanding objects.

show?string

Comma-separated fields to return; all others are left out. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

hide?string

Comma-separated fields to leave out of the response. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

formatted?boolean

When true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.

Defaultfalse

Request Body

The limits of the new link. Send {} for the file's defaults.

application/json
  1. body

The limits of a download link. Every field is optional. On create, a field you leave out takes the file's default.

expires?|

When the link stops working, as an ISO 8601 date or date and time read in the timezone you send. At most 60 days from now. On create, a date in the past is ignored and the file's expires_in_days is used.

Formatdate-time
expires_in_clicks?integer

How many clicks the link allows in all. On create, 0 or no value uses the file's expires_in_clicks.

Range0 <= value
clicks?integer

Update only. Sets how many times the link counts as used.

Range0 <= value
order_id?|

Create only. The order to tie the download to. It is not checked.

product_id?|

Create only. The product to tie the download to. It is not checked.

Response Body

The new download.

application/json
  1. response

A download link to one of your files, usually made for an order item when a product with a file is bought. The link stops working after expires or after expires_in_clicks clicks. A limited token may read a download only when it is bound to it, such as one on the signed-in customer's order.

object*"download"

The object type. Always download.

Value in"download"
url*string

The URL of this download in the API.

Formaturi
download_id*string

The id of the download.

date_created*string

When the download was made.

Formatdate-time
date_modified*string

When the download was last changed.

Formatdate-time
test*boolean

True for a test-mode download.

account_id*string

The account the download belongs to.

file?|

The file, as a link, or the full object when you send expand=file. Left out for tokens that may not read files, such as limited tokens.

order*||

The order the download was made for, as a link, or the full object when you send expand=order. Null when it is not tied to an order.

product*||

The product the download was made for, as a link, or the full object when you send expand=product. Null when it is not tied to a product.

link*string

The link the customer uses to download the file. It ends in the file name.

Formaturi
link_short*string

The same link, ending in dl instead of the file name.

Formaturi
filename*string

The name of the file.

bytes*integer

The size of the file in bytes.

expired*boolean

True when the link no longer works, because it is past expires or out of clicks.

expires?string

When the link stops working. Not returned to limited tokens.

Formatdate-time
expires_in_clicks?integer

How many clicks the link allows in all. Not returned to limited tokens.

clicks?integer

How many times the link has been used. Not returned to limited tokens.

formatted?

Present only when you send formatted=true.

curl -X POST 'https://api.comecero.com/api/v1/files/string/downloads' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "object": "download",  "url": "https://api.comecero.com/api/v1/downloads/0142130710600DoT3ka9Lm",  "download_id": "0142130710600DoT3ka9Lm",  "date_created": "2026-11-02T00:45:12Z",  "date_modified": "2026-11-02T00:45:12Z",  "test": true,  "account_id": "AB1234",  "file": "https://api.comecero.com/api/v1/files/0095012700001FiQ2xT7Ab",  "order": "https://api.comecero.com/api/v1/orders/6622-NXKHE-858",  "product": "https://api.comecero.com/api/v1/products/widget-pro.test",  "link": "https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/widget-pro-setup.zip",  "link_short": "https://cdn.comecero.net/sd/0142130710600DoT3ka9Lm/1/3fa9c2d1/dl",  "filename": "widget-pro-setup.zip",  "bytes": 24518301,  "expired": false,  "expires": "2026-11-09T00:45:12Z",  "expires_in_clicks": 10,  "clicks": 1}

Reset a download POST

Starts a download link over: clicks go back to 0, and the expiry and click limit are set again from the file's `expires_in_days` and `expires_in_clicks`, counted from now. Use it when a customer could not finish a download in time. No request body. Secret and trusted tokens may call it.

Overview

Next Page