File Upload Requests

File upload requests let you collect a file from a customer, reviewer, or support contact under tight purpose, size, and expiry rules. Create one when someone outside your own backend needs to upload a file directly into Commerce.

The upload URL returned on creation is the one URL an external uploader needs to fulfill the request.

The upload request object

An upload request tracks one delegated upload from creation through fulfillment, cancellation, or expiry. When the upload succeeds, it produces a normal Commerce file that you can inspect through Lookup a file.

Properties

Name
active
Type
boolean
Description
Whether the request can still accept an upload.
attemptobjectLatest upload attempt. Returned by lookup and fulfillment after an attempt exists; omitted from create, page, and cancel responses.Click or tap to expand
- Name
  attempted_at
  Type
  timestamp
  Description
  When the upload attempt started.
- Name
  content_type
  Type
  string
  Description
  Declared content type when present.
- Name
  declared_size
  Type
  integer
  Description
  Declared file size in bytes when present.
- Name
  error
  Type
  object
  Description
  Failure details with code, message, retryable, at, and optional param.
- Name
  failed_at
  Type
  timestamp
  Description
  When a failed attempt completed.
- Name
  file_id
  Type
  string
  Description
  Resulting file ID after a successful attempt.
- Name
  filename
  Type
  string
  Description
  Submitted filename when present.
- Name
  id
  Type
  string
  Description
  Unique attempt identifier.
- Name
  ordinal
  Type
  integer
  Description
  One-based attempt number for the request.
- Name
  review
  Type
  object
  Description
  Customer-safe review decision when present.
- Name
  status
  Type
  string
  Description
  Attempt status such as succeeded or failed.
- Name
  succeeded_at
  Type
  timestamp
  Description
  When a successful attempt completed.
- Name
  upload_request_id
  Type
  string
  Description
  Upload-request ID that owns the attempt.
attemptsobjectAttempt policy and audit fields for the upload request.Click or tap to expand
- Name
  attempt_count
  Type
  integer
  Description
  Total upload attempts recorded for this request.
- Name
  failed_attempt_count
  Type
  integer
  Description
  How many upload attempts have failed validation or fulfillment.
- Name
  last_attempted_at
  Type
  timestamp
  Description
  When the most recent upload attempt happened.
- Name
  max_attempts
  Type
  integer
  Description
  Maximum number of allowed failed attempts.
Name
canceled_at
Type
timestamp
Description
When the request was canceled. Returned only after cancellation.
canceled_byobjectActor that canceled the request. Present only after cancellation.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Actor email when available.
- Name
  id
  Type
  string
  Description
  Actor ID when available.
- Name
  name
  Type
  string
  Description
  Actor display name when available.
- Name
  service
  Type
  string
  Description
  Origin label when present.
- Name
  type
  Type
  string
  Description
  Actor type such as api_key, system, or user.
constraintsobjectRequest-specific validation rules layered on top of the selected purpose.Click or tap to expand
- Name
  content_types
  Type
  array
  Description
  Optional narrowed allow-list of MIME types.
- Name
  exact_size
  Type
  integer
  Description
  Optional exact file size in bytes.
- Name
  extensions
  Type
  array
  Description
  Optional narrowed allow-list of filename extensions.
- Name
  filename
  Type
  string
  Description
  Optional exact filename requirement.
- Name
  max_size
  Type
  integer
  Description
  Optional maximum file size in bytes.
- Name
  min_size
  Type
  integer
  Description
  Optional minimum file size in bytes.
Name
created_at
Type
timestamp
Description
When the upload request was created.
Name
custom_data
Type
object
Description
Optional string key-value custom data copied to the resulting file.
displayobjectHuman-facing copy shown to the uploader.Click or tap to expand
- Name
  description
  Type
  string
  Description
  Optional longer explanation of what should be uploaded.
- Name
  help_text
  Type
  string
  Description
  Optional supporting guidance for the uploader.
- Name
  title
  Type
  string
  Description
  Short title for the upload prompt.
Name
expired_at
Type
timestamp
Description
When the request was marked expired. Returned only after expiry is recorded.
Name
expires_at
Type
timestamp
Description
When the public upload URL stops accepting uploads.
Name
file_id
Type
string
Description
Resulting file ID after a successful upload. Omitted until fulfillment succeeds.
Name
fulfilled_at
Type
timestamp
Description
When a valid upload produced the file. Returned only after fulfillment succeeds.
Name
id
Type
string
Description
Unique upload-request identifier. IDs begin with uplreq_.
latest_errorobjectMost recent validation or fulfillment error.Click or tap to expand
- Name
  at
  Type
  timestamp
  Description
  When the error was recorded.
- Name
  code
  Type
  string
  Description
  Stable error code for the failure.
- Name
  message
  Type
  string
  Description
  Human-readable error message.
- Name
  param
  Type
  string
  Description
  Request field associated with the error when available.
- Name
  retryable
  Type
  boolean
  Description
  Whether the uploader can try again.
Name
metadata
Type
object
Description
Service-generated metadata about the upload request. Read-only; use custom_data for caller-supplied data.
Name
purpose
Type
string
Description
File purpose the upload must satisfy:
- product_download for downloadable product files and merchant-managed attachments. Accepts .pdf, .zip, .txt, and .csv files up to 100 MiB. Not linkable through file links.
- product_image for product images. Accepts JPEG, PNG, and GIF up to 10 MiB. Linkable through file links.
- product_video for product videos. Accepts MP4, WebM, and QuickTime up to 250 MiB. Linkable through file links.
- products_import for product-catalog imports. Accepts CSV files up to 32 MiB that follow the required import schema and contain no more than 10,000 data rows. Not linkable through file links.
- support_document for support evidence and attachments. Accepts PDF, JPEG, PNG, and plain text up to 25 MiB. Not linkable through file links.
recipientobjectIntended uploader when you want to record who should provide the file.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Recipient email when available.
- Name
  id
  Type
  string
  Description
  Recipient ID when available.
- Name
  name
  Type
  string
  Description
  Recipient display name when available.
- Name
  type
  Type
  string
  Description
  Recipient type such as customer, email, or user.
requesterobjectActor that created the upload request.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Actor email when available.
- Name
  id
  Type
  string
  Description
  Actor ID when available.
- Name
  name
  Type
  string
  Description
  Actor display name when available.
- Name
  service
  Type
  string
  Description
  Origin label when present.
- Name
  type
  Type
  string
  Description
  Actor type such as api_key, system, or user.
resourceobjectCommerce resource or workflow the file is for.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Resource ID.
- Name
  name
  Type
  string
  Description
  Resource name when available.
- Name
  type
  Type
  string
  Description
  Resource type.
Name
status
Type
string
Description
Upload-request lifecycle status: pending, uploading, fulfilled, expired, canceled, or failed.
subjectobjectPerson or Commerce object the requested file is about.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Subject email when available.
- Name
  id
  Type
  string
  Description
  Subject ID when available.
- Name
  name
  Type
  string
  Description
  Subject display name when available.
- Name
  type
  Type
  string
  Description
  Subject type such as customer, case, or user.
Name
updated_at
Type
timestamp
Description
When the upload request was last updated.
Name
upload_url
Type
string
Description
Bearer upload URL returned only by a successful create response. It is not returned by lookup, page, or cancel. Store it securely and share it only with the intended uploader.
Name
uploading_at
Type
timestamp
Description
When an upload attempt moved into active fulfillment. Returned only while or after an upload attempt has started.

When attempt.review is present, its public fields are created_at, decision, optional file_id, optional public_message, optional reasons, reviewed_at, and type. Each reason contains code, message, and optional param.

For products_import, every nonblank data row must contain at least these columns in order: name, type, price_currency, price_value, reference, description, about, category, tax_code, unit_dimension, price_label, publish, and attributes. An optional first header row may use those names in the same order. The file must contain between 1 and 10,000 data rows.

Create an upload request

Create a delegated upload request for someone else to fulfill. The returned upload_url is a bearer capability, so send it only to the intended uploader.

Constraints can narrow a purpose, but they cannot widen it. For example, you can require PDF only for support_document, but you cannot allow an image type the selected purpose would normally reject.

Request body

attemptsobjectOptional retry policy for the upload request.Click or tap to expand
- Name
  max_attempts
  Type
  integer
  Description
  Maximum number of allowed failed attempts. Defaults to 3.
constraintsobjectOptional narrowed validation rules for the uploaded file.Click or tap to expand
- Name
  content_types
  Type
  array
  Description
  Optional narrowed allow-list of MIME types.
- Name
  exact_size
  Type
  integer
  Description
  Optional exact file size in bytes.
- Name
  extensions
  Type
  array
  Description
  Optional narrowed allow-list of filename extensions.
- Name
  filename
  Type
  string
  Description
  Optional exact filename requirement.
- Name
  max_size
  Type
  integer
  Description
  Optional maximum file size in bytes.
- Name
  min_size
  Type
  integer
  Description
  Optional minimum file size in bytes.
Name
custom_data
Type
object
Description
Optional string key-value custom data copied onto the resulting file. The encoded object can be at most 25 KiB, and each key can be at most 256 characters.
displayobjectOptional uploader-facing copy.Click or tap to expand
- Name
  description
  Type
  string
  Description
  Optional longer description of what to upload.
- Name
  help_text
  Type
  string
  Description
  Optional supporting guidance for the uploader.
- Name
  title
  Type
  string
  Description
  Short title for the upload prompt.
Name
expires_at
Type
timestamp
Description
Optional RFC 3339 expiry. The default is 24 hours from creation.
Name
purpose
Type
string
Description
File purpose the upload must satisfy.
recipientobjectOptional uploader identity details.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Recipient email when available.
- Name
  id
  Type
  string
  Description
  Recipient ID when available.
- Name
  name
  Type
  string
  Description
  Recipient display name when available.
- Name
  type
  Type
  string
  Description
  Recipient type.
requesterobjectOptional actor creating the request. Defaults to { "type": "api_key" }.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Actor email when available.
- Name
  id
  Type
  string
  Description
  Actor ID when available.
- Name
  name
  Type
  string
  Description
  Actor display name when available.
- Name
  type
  Type
  string
  Description
  Actor type.
resourceobjectOptional Commerce resource or workflow that needs the file.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Resource ID.
- Name
  name
  Type
  string
  Description
  Resource name when available.
- Name
  type
  Type
  string
  Description
  Resource type.
subjectobjectOptional person or Commerce object the requested file is about.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Subject email when available.
- Name
  id
  Type
  string
  Description
  Subject ID when available.
- Name
  name
  Type
  string
  Description
  Subject display name when available.
- Name
  type
  Type
  string
  Description
  Subject type.

Defaults and validation

expires_at must be in the future and defaults to 24 hours after creation. attempts.max_attempts must be nonnegative and defaults to 3; attempt counters and audit fields are response-only.
min_size, max_size, and exact_size must be nonnegative. Exact size must fit the minimum, maximum, and selected purpose. Minimum cannot exceed maximum or the purpose maximum.
Content types are normalized without parameters, and extensions are normalized with a leading dot. Each supplied type or extension must be allowed by the selected purpose.
An exact filename must use an extension allowed by the selected purpose. Constraints can narrow a purpose but cannot widen it.

Response

The response returns a top-level upload_request object and includes upload_url only in this successful create response. Store the URL immediately; later lookup, page, and cancel responses do not reissue it.

Request

POST

/upload_requests/create

curl https://api.zebo.dev/upload_requests/create \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Idempotency-Key: support-doc-upload-001" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "support_document",
    "constraints": {
      "content_types": ["application/pdf"],
      "max_size": 10485760
    },
    "display": {
      "title": "Upload dispute evidence",
      "help_text": "Attach a PDF under 10 MB."
    },
    "recipient": { "type": "customer", "email": "[email protected]" },
    "resource": { "type": "dispute", "id": "disp_123" },
    "custom_data": { "case_id": "CASE-1001" },
    "expires_at": "2026-07-06T12:30:00Z"
  }'

{
  "upload_request": {
    "id": "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
    "purpose": "support_document",
    "status": "pending",
    "active": true,
    "upload_url": "<UPLOAD_URL>",
    "constraints": {
      "content_types": ["application/pdf"],
      "max_size": 10485760
    },
    "display": {
      "help_text": "Attach a PDF under 10 MB.",
      "title": "Upload dispute evidence"
    },
    "subject": {},
    "recipient": { "type": "customer", "email": "[email protected]" },
    "resource": { "type": "dispute", "id": "disp_123" },
    "requester": { "type": "api_key" },
    "attempts": {
      "max_attempts": 3,
      "attempt_count": 0,
      "failed_attempt_count": 0
    },
    "custom_data": { "case_id": "CASE-1001" },
    "created_at": "2026-06-05T12:30:00Z",
    "updated_at": "2026-06-05T12:30:00Z",
    "expires_at": "2026-07-06T12:30:00Z"
  }
}

Fulfill an upload request

Fulfillment is the public multipart endpoint behind upload_request.upload_url. It does not use API-key authentication; the complete returned URL is the bearer capability. Use that URL unchanged and do not construct its query values yourself.

Query parameters

Name
id
Type
string
Description
Public upload-request capability ID.
Name
token
Type
string
Description
Bearer token paired with the capability ID.

Request body

Name
file
Type
file
Description
Multipart file part supplied by the uploader.

Response

On success, the API returns 200 OK with the fulfilled upload_request, including its latest attempt, and a restricted file receipt. The receipt contains required content_type, created_at, id, size, and status, plus optional filename and name. It does not contain the full file metadata; have an authenticated backend call Lookup a file with the receipt ID when it needs that object.

When file validation fails, the API returns 400 Bad Request with the updated upload_request, including the failed latest attempt, and a top-level error containing required code, message, and retryable, plus optional param. The failed attempt and latest error remain visible through lookup. A retryable failure leaves the request pending while attempts remain; a non-retryable failure or the final allowed failed attempt changes the request to failed and inactive.

An unknown request or invalid URL token returns 404; an inactive, expired, or exhausted request returns 410; insufficient file quota returns 409; and a temporarily unavailable upload returns 503.

Request

POST

/upload_requests/upload

curl "<UPLOAD_URL>" \
  -F "file=@./evidence.pdf;type=application/pdf"

Lookup an upload request

Retrieve an upload request by ID. Use lookup after sharing an upload URL to check whether the request is still pending, failed validation, expired, canceled, or fulfilled.

Request body

Name
id
Type
string
Description
Upload-request ID to retrieve.

Response

The response returns a top-level upload_request object and includes its latest attempt when one exists. It does not reissue upload_url.

Request

POST

/upload_requests/lookup

curl https://api.zebo.dev/upload_requests/lookup \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"uplreq_1gK9pQ4vL8mN2sT5wX7yZ0"}'

Page upload requests

List delegated upload requests for the authorized application. Filters let you review outstanding requests by purpose, status, or associated Commerce resource.

Request body

Name
page_number
Type
integer
Description
Page number to retrieve. Defaults to 1.
Name
page_size
Type
integer
Description
Requested number of upload requests per page. Defaults to 25 and is capped at 256.
Name
purpose
Type
string
Description
Optional purpose filter.
resourceobjectOptional resource filter.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Resource ID.
- Name
  name
  Type
  string
  Description
  Resource name when available.
- Name
  type
  Type
  string
  Description
  Resource type.
Name
status
Type
string
Description
Optional status filter: pending, uploading, fulfilled, expired, canceled, or failed.

Response

Requests are returned newest first. The response returns a top-level page object with upload_requests, number, and size; size is the number returned, not the requested limit. An exhausted page returns upload_requests: [] and size: 0. Page numbers and sizes below 1 are normalized to their defaults. Page items do not include the latest attempt; use lookup when you need it.

Request

POST

/upload_requests/page

curl https://api.zebo.dev/upload_requests/page \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"support_document","status":"pending","page_number":1,"page_size":25}'

Cancel an upload request

Cancel a delegated upload request so its public upload URL can no longer accept files. Cancel pending requests when the underlying case closes, the recipient should no longer upload, or you issued a replacement request.

Request body

canceled_byobjectOptional actor canceling the request.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Actor email when available.
- Name
  id
  Type
  string
  Description
  Actor ID when available.
- Name
  name
  Type
  string
  Description
  Actor display name when available.
- Name
  type
  Type
  string
  Description
  Actor type.
Name
id
Type
string
Description
Upload-request ID to cancel.

Response

The response returns the updated upload_request with status set to canceled. It does not include upload_url or a latest-attempt aggregate.

Request

POST

/upload_requests/cancel

curl https://api.zebo.dev/upload_requests/cancel \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Idempotency-Key: cancel-upload-request-001" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
    "canceled_by": { "type": "user", "id": "usr_support_123" }
  }'