Files API

For AI assistants: the facts every SparkLayer API call needs

Base URLs: Live https://app.sparklayer.io, test https://test.app.sparklayer.io. Each environment has its own data and its own API keys.
Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
Access token: POST {base}/api/auth/token with a Site-Id header and a JSON body (not form-encoded): {"grant_type":"client_credentials","client_id":"…","client_secret":"…"}. It returns access_token, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
Every request: Authorization: Bearer <access_token> and Site-Id: <site id>, plus Content-Type: application/json when there is a body. Set a User-Agent that names your integration.
Errors: RFC 7807 problem details: title, status, detail and an optional errors[] of { code, message, property }. Some error responses have no body. Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409s with exponential backoff; on 401, get a new token once and retry; don't retry other 4xx without changing the request.
Pagination: Most list endpoints return everything. GET /api/v2/price-lists pages with page and page_size (up to 250) until pagination.current_page equals total_pages. GET /api/v1/purchases uses limit (up to 500) and offset: stop when a page has fewer than limit results.
Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer GET /api/v2/price-lists over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.
Read the docs as Markdown: Add .md to any page URL. Index of every page: docs.sparklayer.io/llms.txt. Every API operation, compactly: docs.sparklayer.io/llms-api.txt. The developer guides in full: docs.sparklayer.io/developers/llms.txt.
OpenAPI specs: core, ordering, pricing, purchasing, stock, files, sync-log: https://docs.sparklayer.io/openapi/<api>.yaml (also .json). Ignite: https://docs.sparklayer.io/openapi/ignite.yaml.
MCP: Search and read these docs from your assistant with the docs MCP server at https://docs.sparklayer.io/mcp.

Build with AI: ready-made prompts and MCP setup

The Files API stores and retrieves files in SparkLayer. SparkLayer uses it for order file attachments, and you can use it to upload files or download the files attached to your orders.

How it works

URLs expire

The upload and download URLs returned by the API expire after 15 minutes.

Uploading a file

Uploading takes two requests:

Create a file (POST /api/v1/files) with the file's path, including its name, in file_path. Like every API request, it needs your access token and Site ID:
Create a file
```
curl -X POST https://app.sparklayer.io/api/v1/files \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Site-Id: <SITE_ID>" \
  -H "Content-Type: application/json" \
  -d '{ "file_path": "folder/file.pdf" }'
```
The response includes the file's id, a signed upload url and a list of required_headers.
Upload the file's contents with an HTTP PUT to that url, sending every header in required_headers (for example Content-Type). If any are missing, the upload fails. The signed URL grants access by itself, so this request doesn't need your Authorization or Site-Id headers:
Upload the contents
```
curl --upload-file 'file.pdf' \
  -H "Content-Type: application/pdf" \
  '<UPLOAD_URL>'
```

Files can be up to 20 MB. Use the file's id with the other endpoints. To replace a file's contents, update the file (PATCH /api/v1/files/{id}) to get a new upload URL, then upload again.

To download a file, get the file (GET /api/v1/files/{id}). Once the upload has completed, this returns a download URL, some file metadata and a list of required_headers. Download the file from the URL, sending those headers.

Failed uploads

If the file's contents don't match its file extension, the file is deleted, and GET /api/v1/files/{id} returns 410 Gone.

Downloading order file attachments

To download the files attached to a B2B order, use GET /api/v1/files/{id}. SparkLayer stores the IDs of attached files in the order's note attributes, under the name set in checkoutCustomElements in your theme (file-upload by default). They're stored as a JSON array:

Order note attribute

[
  "gid://sparklayer/File/fdc70d92-fcdf-4719-af2b-9d319a5035d2",
  "gid://sparklayer/File/a7a3ee08-c6d0-49ee-89b4-bcdaf780d553",
  "gid://sparklayer/File/15be5381-0b50-459f-9643-af236b9f29f7"
]

Remove the gid://sparklayer/File/ prefix from each one to get the file ID, for example fdc70d92-fcdf-4719-af2b-9d319a5035d2.

Endpoints

Next steps

Authentication: get the access token the API requests need.
Custom attributes and files: let customers attach files to cart items.
Purchasing API: look up the orders the files belong to.

Was this page helpful?

Last updated 7 October 2026