Digital Files API

Manage the downloadable file attached to a digital product variant. Uploads use multipart/form-data. When a customer buys a digital variant, Easel issues a download link for the file. See Order Downloads for the customer-facing side.

The variant’s product must have digital delivery. Create one through the API with POST /api/v1/products/ and "delivery": "digital" (see Products), or create it in the admin panel. A physical variant cannot carry a digital file.

Endpoints

• Get Digital File - GET /api/v1/products/{product_id}/variants/{variant_id}/digital-file/
• Upload Digital File - POST /api/v1/products/{product_id}/variants/{variant_id}/digital-file/
• Delete Digital File - DELETE /api/v1/products/{product_id}/variants/{variant_id}/digital-file/

A variant carries at most one digital file, so there is no list endpoint and the file is addressed through its variant rather than by file ID. Uploading a file attaches it to the variant, replacing any file already attached.

Get Digital File

Return the file attached to a digital product variant.

Endpoint: GET /api/v1/products/{product_id}/variants/{variant_id}/digital-file/

Scope Required: products:read

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/variants/prv_d0b6fmv28q6vn14peun0/digital-file/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "id": "pdf_d0b6fmv28q6vn14peun0",
  "file_name": "ebook.pdf",
  "file_size": 1048576,
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Error Responses

File not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Upload Digital File

Attach a file to a digital product variant. Send the file as a part in a multipart/form-data body. If the body contains more than one file, only the first is stored.

Endpoint: POST /api/v1/products/{product_id}/variants/{variant_id}/digital-file/

Scope Required: products:write

Limits

• The file must be 500 MiB or smaller.

Request

curl -X POST "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/variants/prv_d0b6fmv28q6vn14peun0/digital-file/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -F "file=@ebook.pdf"

Response

Status: 201 Created

{
  "id": "pdf_d0b6fmv28q6vn14peun0",
  "file_name": "ebook.pdf",
  "file_size": 1048576,
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Error Responses

Missing file

Status: 400 Bad Request

{
  "error": "file is required",
  "code": "MISSING_FIELD"
}

Variant not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

File too large

Status: 413 Request Entity Too Large

{
  "error": "File exceeds maximum size of 524288000 bytes",
  "code": "FILE_TOO_LARGE"
}

Delete Digital File

Delete the file attached to a variant.

Endpoint: DELETE /api/v1/products/{product_id}/variants/{variant_id}/digital-file/

Scope Required: products:write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/variants/prv_d0b6fmv28q6vn14peun0/digital-file/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Error Responses

File not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Digital File Object

Fields