Files

Every file in a store is one of two kinds, and each kind has its own pair of scopes. Which one you use depends on what the file is for.

upload is for files the merchant attaches to their catalog — product photos, brand logos, and anything that shows up in a product form, the media library, or the file picker. Use the read_files and write_files scopes.

site_asset is for files the storefront itself renders — logos, hero banners, favicons, and theme images that live in the online-store builder and theme editor. Use the read_site_assets and write_site_assets scopes.

A few endpoints work with either kind and figure out which scope to enforce from the file's type — for those, both scopes are listed and the description says which one actually applies. Storage is shared: uploads and site assets draw from the same quota.

Endpoints#

Files limits

GET read_files + read_site_assets

Get the size caps, allowed formats, and per-upload limits.

Returns the store's current file limits and supported formats. Use this response to configure validation and pagination; do not copy these values into your app because platform limits can change.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    Token's per-window quota exceeded. Retry after the Retry-After header.

Files quota

GET read_files + read_site_assets

See how much storage the store has used.

Returns used and available storage for the store. Media-library files and site assets share this quota. Treat the upload response as authoritative because another upload can change usage after this check.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    Token's per-window quota exceeded. Retry after the Retry-After header.

List files

GET read_files + read_site_assets

Browse the store's files, page by page.

Returns one file namespace at a time. Omit type or use upload for the Media library; use site_asset for storefront assets. The namespace determines whether the call requires read_files or read_site_assets. Filter with media, search by filename with search, and use the returned pagination fields to continue.

Query parameters

Name Type Description
type string

File namespace. Omit or use upload for Media-library files; use site_asset for storefront assets.

Example: upload
media string

Filter by media type: image, video, document, or 3d.

Example: image
search string

Free-text filename match (case-insensitive substring).

Example: outdoor
page integer

Page number.

Example: 1
limit integer

Page size.

Example: 20

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    Token's per-window quota exceeded. Retry after the Retry-After header.

  • 400 STORAGE_INVALID_FILE_TYPE

    type must be upload or site_asset.

  • 400 STORAGE_MEDIA_TYPE_INVALID

    media must be image, video, document, or 3d.

  • 400 STORAGE_INVALID_REQUEST

    Pagination or filter parameters are out of range.

Upload one or more files

POST write_files + write_site_assets

Send one or more files to the store.

Post your files as multipart/form-data — one or more file parts, plus an optional type field. Use upload (the default) for things the merchant attaches to their catalog, like product images and brand logos; use site_asset for things the storefront renders, like logos, hero banners, and favicons. Your token needs write_files for uploads or write_site_assets for site assets.

Accepted formats. Images: JPG, PNG, GIF, WEBP. Video: MP4. Documents: PDF, CSV. 3D models: GLB, USDZ. Call GET /files/limits for the size caps and this list at runtime.

Set the right Content-Type on each file part. It must match the file's actual format. If it is missing or application/octet-stream, the API uses the filename extension. Files that do not match their declared format, are unsupported, exceed current limits, or fail security validation are rejected with a coded error.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    Token's per-window quota exceeded. Retry after the Retry-After header.

  • 400 STORAGE_INVALID_MULTIPART

    The request is not valid multipart/form-data.

  • 400 STORAGE_NO_FILES_PROVIDED

    The request had no file parts.

  • 400 STORAGE_INVALID_FILE_TYPE

    type form field must be upload or site_asset.

  • 400 STORAGE_MAX_FILES_PER_UPLOAD

    The batch exceeds the maximum files per upload.

  • 400 STORAGE_FILE_TOO_LARGE

    A file exceeds its media-type size cap. See files.limits for the per-type cap.

  • 400 STORAGE_IMAGE_MEGAPIXELS_TOO_BIG

    An image exceeds the megapixel cap.

  • 400 STORAGE_CONTENT_TYPE_MISMATCH

    A file's bytes don't match the declared MIME type.

  • 400 STORAGE_MALWARE_REJECTED

    The file was rejected by the malware scanner.

  • 400 STORAGE_QUOTA_EXCEEDED

    The store's storage quota would be exceeded. Free up space or split the batch.

  • 400 STORAGE_BATCH_QUOTA_EXCEEDED

    The whole batch would exceed the quota. Reduce the batch size.

Get info for many files

POST read_files + read_site_assets

Look up several files at once.

Returns metadata for the requested file ids. The token must have the read scope required by every returned file: read_files for Media-library files and read_site_assets for site assets. The request fails when a required scope is missing; it does not return per-file authorization results.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
file_ids required array<string>

File ids to look up.

Example: ["f_abc", "f_def"]

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    Token's per-window quota exceeded. Retry after the Retry-After header.

  • 400 STORAGE_FILE_IDS_REQUIRED

    The body must include a non-empty file_ids array.

  • 400 STORAGE_BULK_LOOKUP_MAX_EXCEEDED

    The batch exceeds the maximum files per lookup.

  • 404 STORAGE_FILE_NOT_FOUND

    One or more file ids do not exist (or belong to another store).

Get a file

GET read_files + read_site_assets

Fetch a single file's details.

Returns everything about one file — its type, its CDN URL, when it was uploaded, and its metadata. The scope follows the file's type: read_files for uploads, read_site_assets for site assets.

Path parameters

Name Type Description
id required integer

File id.

Example: 7

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    Token's per-window quota exceeded. Retry after the Retry-After header.

  • 404 STORAGE_FILE_NOT_FOUND

    No file with that id in the store.

Update a file

PUT write_files + write_site_assets

Rename a file or set its alt text.

Change the file's display name (original_filename) or its alt_text. Alt text is the description screen readers announce, so set it for every image that shows up on a storefront — it's good for accessibility and for SEO. The scope follows the file's type: write_files for uploads, write_site_assets for site assets.

Path parameters

Name Type Description
id required integer

File id.

Example: 7

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
original_filename string

New filename. Empty string is rejected.

Example: outdoor-photo.jpg
alt_text string

Accessibility text for screen readers. Apply to every image that ships to a storefront.

Example: Red hiking backpack on a rock

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    Token's per-window quota exceeded. Retry after the Retry-After header.

  • 400 INVALID_REQUEST

    The body is malformed.

  • 400 STORAGE_FILENAME_REQUIRED

    original_filename was provided as an empty string.

  • 400 STORAGE_FILENAME_TOO_LONG

    original_filename exceeds the max length.

  • 400 STORAGE_ALT_TEXT_TOO_LONG

    alt_text exceeds the max length.

  • 404 STORAGE_FILE_NOT_FOUND

    No file with that id in the store.

Delete a file

DELETE write_files + write_site_assets

Remove a file from the store.

Deletes the file when it has no references. If removable references exist, the first request returns CONFIRMATION_REQUIRED; repeat it with the returned token to detach those references and delete. References marked as blocked cannot be force-deleted and must be removed at their source first. The file type determines the required write scope.

Path parameters

Name Type Description
id required integer

File id.

Example: 7

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
confirmed boolean

On a confirmation retry, set this to true and send the returned confirmation_token. Omit it on the first request.

confirmation_token string

Token from the CONFIRMATION_REQUIRED response. Omit it on the first request and resend the exact same id selection when using it.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    Token's per-window quota exceeded. Retry after the Retry-After header.

  • 400 INVALID_REQUEST

    The body is malformed.

  • 400 STORAGE_INVALID_CONFIRMATION

    confirmation_token is missing, expired, or mismatched.

  • 400 STORAGE_FILE_DELETE_BLOCKED

    The file is required by another resource and cannot be force-deleted. Remove that reference first.

  • 404 STORAGE_FILE_NOT_FOUND

    No file with that id in the store.

  • 409 CONFIRMATION_REQUIRED

    Returned on the first attempt. Re-send the request with confirmed: true and the confirmation_token from this response to force the delete.

Delete many files

POST write_files + write_site_assets

Remove several files in one call.

Deletes a list of files together, all or nothing. Each file's type decides which scope it needs. If any file in the list is still attached somewhere that requires it, the whole call returns a confirmation token and deletes nothing — send it again with confirmed: true and the confirmation_token to force it through, or drop that file from the list and retry.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
file_ids required array<string>

File ids to delete.

Example: ["f_abc", "f_def"]
confirmed boolean

Set to true to acknowledge the confirmation warning and force-delete files that are still attached to a required resource.

Example: false
confirmation_token string

Token returned by the first call when confirmation is required.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.

  • 403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN

    Token is valid but lacks the required scope for this call.

  • 429 RATE_LIMITED

    Token's per-window quota exceeded. Retry after the Retry-After header.

  • 400 STORAGE_FILE_IDS_REQUIRED

    The body must include a non-empty file_ids array.

  • 400 STORAGE_BULK_DELETE_MAX_EXCEEDED

    The batch exceeds the maximum files per delete.

  • 400 STORAGE_INVALID_CONFIRMATION

    confirmation_token is missing, expired, or mismatched.

  • 400 STORAGE_FILE_DELETE_BLOCKED

    At least one file is required by another resource and cannot be force-deleted. Remove the blocking reference first.

  • 404 STORAGE_FILE_NOT_FOUND

    One or more file ids do not exist (or belong to another store).

  • 409 CONFIRMATION_REQUIRED

    Returned on the first attempt. Re-send with confirmed: true and the confirmation_token from this response.