Files API

Our files API is designed to store and retrieve any files in our system. For example, we use this for order file attachments.

You can use this API to retrieve the files attached to your orders. More details later

Important note: the URLs returned by the API to download/upload files have a expiry time of 15 minutes.

To create a file, use the POST endpoint /api/v1/files. This takes a file path in the body, and will return a URL, some headers and some other information. You can then upload a file to this URL, using the headers provided. You must include these headers, or the file upload will fail.

For example, to upload the file using cURL:

This endpoint will also return an ID for the file, which can be used for the other endpoints.

You can update the file by using the PATCH endpoint /api/v1/files/{id}, using the ID returned when creating the file.

To download a file, use the GET endpoint /api/v1/files/{id}. When the file upload has successfully completed, this will return a download URL, along with some file metadata. As with the upload endpoint, it will return a list of headers you must include.

You can then download the file from the provided URL.

If the mime type of the file you upload does not match the file extension, the file will be deleted, and the GET endpoint /api/v1/files/{id} will return a 410 GONE status code.

If you would like to download any files attached to one of your B2B orders, you can use the GET endpoint /api/v1/files/{id}. We store the IDs of attached files in the note attributes of the order, under the name you provide in your checkoutCustomElements in your theme (by default this is file-upload). They are stored as a JSON array like the following:

You must extract the UUIDs from these GID strings, removing the gid://sparklayer/File prefix. This is what the UUID should look like: fdc70d92-fcdf-4719-af2b-9d319a5035d2