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 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
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
403STORE_ADMIN_TOKEN_RUNTIME_FORBIDDENToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDToken's per-window quota exceeded. Retry after the Retry-After header.
Files quota
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
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
403STORE_ADMIN_TOKEN_RUNTIME_FORBIDDENToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDToken's per-window quota exceeded. Retry after the Retry-After header.
List files
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 |
media
|
string |
Filter by media type: |
search
|
string |
Free-text filename match (case-insensitive substring). |
page
|
integer |
Page number. |
limit
|
integer |
Page size. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
403STORE_ADMIN_TOKEN_RUNTIME_FORBIDDENToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDToken's per-window quota exceeded. Retry after the Retry-After header.
-
400STORAGE_INVALID_FILE_TYPEtypemust beuploadorsite_asset. -
400STORAGE_MEDIA_TYPE_INVALIDmediamust beimage,video,document, or3d. -
400STORAGE_INVALID_REQUESTPagination or filter parameters are out of range.
Upload one or more files
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
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
403STORE_ADMIN_TOKEN_RUNTIME_FORBIDDENToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDToken's per-window quota exceeded. Retry after the Retry-After header.
-
400STORAGE_INVALID_MULTIPARTThe request is not valid multipart/form-data.
-
400STORAGE_NO_FILES_PROVIDEDThe request had no
fileparts. -
400STORAGE_INVALID_FILE_TYPEtypeform field must beuploadorsite_asset. -
400STORAGE_MAX_FILES_PER_UPLOADThe batch exceeds the maximum files per upload.
-
400STORAGE_FILE_TOO_LARGEA file exceeds its media-type size cap. See
files.limitsfor the per-type cap. -
400STORAGE_IMAGE_MEGAPIXELS_TOO_BIGAn image exceeds the megapixel cap.
-
400STORAGE_CONTENT_TYPE_MISMATCHA file's bytes don't match the declared MIME type.
-
400STORAGE_MALWARE_REJECTEDThe file was rejected by the malware scanner.
-
400STORAGE_QUOTA_EXCEEDEDThe store's storage quota would be exceeded. Free up space or split the batch.
-
400STORAGE_BATCH_QUOTA_EXCEEDEDThe whole batch would exceed the quota. Reduce the batch size.
Get info for many files
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. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
403STORE_ADMIN_TOKEN_RUNTIME_FORBIDDENToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDToken's per-window quota exceeded. Retry after the Retry-After header.
-
400STORAGE_FILE_IDS_REQUIREDThe body must include a non-empty
file_idsarray. -
400STORAGE_BULK_LOOKUP_MAX_EXCEEDEDThe batch exceeds the maximum files per lookup.
-
404STORAGE_FILE_NOT_FOUNDOne or more file ids do not exist (or belong to another store).
Get a file
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. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
403STORE_ADMIN_TOKEN_RUNTIME_FORBIDDENToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDToken's per-window quota exceeded. Retry after the Retry-After header.
-
404STORAGE_FILE_NOT_FOUNDNo file with that id in the store.
Update a file
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. |
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. |
alt_text
|
string |
Accessibility text for screen readers. Apply to every image that ships to a storefront. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
403STORE_ADMIN_TOKEN_RUNTIME_FORBIDDENToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDToken's per-window quota exceeded. Retry after the Retry-After header.
-
400INVALID_REQUESTThe body is malformed.
-
400STORAGE_FILENAME_REQUIREDoriginal_filenamewas provided as an empty string. -
400STORAGE_FILENAME_TOO_LONGoriginal_filenameexceeds the max length. -
400STORAGE_ALT_TEXT_TOO_LONGalt_textexceeds the max length. -
404STORAGE_FILE_NOT_FOUNDNo file with that id in the store.
Delete a file
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. |
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
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
403STORE_ADMIN_TOKEN_RUNTIME_FORBIDDENToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDToken's per-window quota exceeded. Retry after the Retry-After header.
-
400INVALID_REQUESTThe body is malformed.
-
400STORAGE_INVALID_CONFIRMATIONconfirmation_tokenis missing, expired, or mismatched. -
400STORAGE_FILE_DELETE_BLOCKEDThe file is required by another resource and cannot be force-deleted. Remove that reference first.
-
404STORAGE_FILE_NOT_FOUNDNo file with that id in the store.
-
409CONFIRMATION_REQUIREDReturned on the first attempt. Re-send the request with
confirmed: trueand theconfirmation_tokenfrom this response to force the delete.
Delete many files
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. |
confirmed
|
boolean |
Set to |
confirmation_token
|
string |
Token returned by the first call when confirmation is required. |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
403STORE_ADMIN_TOKEN_RUNTIME_FORBIDDENToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDToken's per-window quota exceeded. Retry after the Retry-After header.
-
400STORAGE_FILE_IDS_REQUIREDThe body must include a non-empty
file_idsarray. -
400STORAGE_BULK_DELETE_MAX_EXCEEDEDThe batch exceeds the maximum files per delete.
-
400STORAGE_INVALID_CONFIRMATIONconfirmation_tokenis missing, expired, or mismatched. -
400STORAGE_FILE_DELETE_BLOCKEDAt least one file is required by another resource and cannot be force-deleted. Remove the blocking reference first.
-
404STORAGE_FILE_NOT_FOUNDOne or more file ids do not exist (or belong to another store).
-
409CONFIRMATION_REQUIREDReturned on the first attempt. Re-send with
confirmed: trueand theconfirmation_tokenfrom this response.