Product files
The downloadable files attached to a product, and the metadata on each.
Downloadables attached to a product. What a grant is and how delivery works are on Digital products and downloads.
List product downloads
/api/v1/kahunacart/products/{id}/files
The downloadable files attached to a product, with their file name, the title and description customers read (null when unset, and the file name shows instead), size, download limit, expiry, position and the release each belongs to, and variant_id when it goes only to one variant's buyers. A file with no release is evergreen and is offered to every buyer of the product; files work on physical products too, so every pressing of a record can come with its download. Uploading bytes is not available through this interface.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
Update a product download
/api/v1/kahunacart/products/{id}/files/{fileId}
Edit a downloadable's metadata: what the customer's browser saves it as, the title and description customers read for it, how many times it may be downloaded, how long the link lives, where it sits in the list, and which variant's buyers get it (variant_id; null gives it to every buyer of the product, a physical product's included). The bytes themselves are immutable, because grants already issued promised a specific file to a specific buyer.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
| fileId required | integer | Product file id |
| name optional | string | Display name the customer downloads it as |
| title optional | string or null | What customers read for the file, e.g. "Typhoon One-Page (Publisher)"; empty or null clears it and the file name shows instead |
| description optional | string or null | A sentence or two shown under the title; empty or null clears it |
| download_limit optional | integer or null | Downloads allowed per grant; null for unlimited |
| expiry_days optional | integer or null | Days a grant stays live; null for no expiry |
| position optional | integer | |
| variant_id optional | integer or null | One of this product's variants, so only its buyers get the file from now on; null for every buyer of the product. A variant of another product is refused with 422. Grants already made are left alone |
Delete a product download
/api/v1/kahunacart/products/{id}/files/{fileId}
Detach a downloadable from its product and delete the bytes on disk. Existing grants keep their rows as the audit trail of who was given what, and start answering not_found once the file is gone.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
| fileId required | integer | Product file id |
Upload a product file
/api/v1/kahunacart/products/{id}/files
Upload a downloadable file for a product. multipart/form-data; capped by downloads.max_upload_mb. Optional name, title, description, variant_id (one of this product's variants, so only its buyers get the file; a variant of another product is a 422), download_limit, expiry_days, position, and grant_past_orders=1 to give it to earlier buyers too (the answer's granted counts the grants made).
The upload accepts name, variant_id, download_limit, expiry_days and position alongside the bytes. A file over downloads.max_upload_mb is a 413, and an extension outside the allowlist is a 422. The bytes are immutable, so replacing a file means uploading a new one, and path and release_id are not editable through PATCH.