Have the sandbox buyer ask to cancel an order

POST /sandbox/orders/{orderId}/cancellation-requests

Sandbox only: the production API does not serve this operation. Snapcaster's sandbox buyer asks the seller to cancel an order, the whole order or some of its lines, with an optional reason, exactly as a buyer does from their order page. It works only on an order from this seller's own test purchase; any other order returns 404 ORDER_NOT_FOUND. Snapcaster emails the seller and sends order.cancellation_request.created, the same as for a real buyer. Answer it with POST /orders/{orderId}/cancellation-requests/{requestId}/decline, or honor it by cancelling the lines. A retry with the same Idempotency-Key and body replays the first response. Returns the pending request.

Example

These examples send requests to the sandbox.

Replace the example orderId in the URL with your own.

cURL request - Sandbox: Cancel one unit of a line

curl --request POST \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/sandbox/orders/ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW/cancellation-requests' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header 'Content-Type: application/json' \
  --data '{
  "lines": [
    {
      "lineRef": "oln_1f0c8a4d7e2b45c9a1d6f3b8e07c9241",
      "quantity": 1
    }
  ],
  "reason": "Ordered the wrong printing"
}'

$(uuidgen) makes a new Idempotency-Key each time you run the command. To retry a command after a lost response, send the key from the first attempt.

Response 201: Pending request

{
  "success": true,
  "data": {
    "id": "cnr_8d3f2a61b0c94e7f9a15c2d48e6b7031",
    "order_id": "ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW",
    "status": "pending",
    "reason": "Ordered the wrong printing",
    "resolution_note": null,
    "created_at": "2026-09-04T19:01:12.000Z",
    "resolved_at": null,
    "lines": [
      {
        "line_ref": "oln_1f0c8a4d7e2b45c9a1d6f3b8e07c9241",
        "sku_id": 14602,
        "quantity": 1
      }
    ]
  }
}

Endpoint

Environment	URL
Sandbox	`https://api-sandbox.snapcaster.ca/api/v1/marketplace/sandbox/orders/{orderId}/cancellation-requests`

Authentication

marketplaceApiKey - http bearer. Send the seller's marketplace API key as Authorization: Bearer mp_{sellerCode}_{hex}. The mp_{sellerCode}_ prefix identifies the seller; the trailing hex is the secret. The seller generates the key and supplies it to your platform.

Request

Path parameters

orderId string required

The opaque public order id (the webhook/poll order_id).

Constraints: minimum length: 1 Example ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW

Headers

Idempotency-Key string required

Keep this UUID when retrying the same order operation and body. Keys remain valid for the lifetime of the order. Changed contents return 409 IDEMPOTENCY_CONFLICT; a concurrent attempt returns 409 REQUEST_IN_PROGRESS with Retry-After.

Constraints: format: uuid Example f04e4a96-3c99-44dc-abce-5b6862c589c9

X-Snapcaster-Api-Version string

Override the platform pin for this request only. Webhook versions and the platform pin do not change.

Constraints: allowed values: 2026-10 Example 2026-10

Request body

lines array of object

The line items in this request, response, or event.

Constraints: minimum items: 1

Show child fieldsHide child fields

lines[].lineRef string

The purchase-line ref (oln_…) of the order line this entry names, read from the order's own lines. Name a line by lineRef or by skuId; lineRef is needed only when the SKU is on more than one line the command can still act on.

Constraints: pattern: ^oln_[0-9a-f]{32}$ Example oln_1f0c8a4d7e2b45c9a1d6f3b8e07c9241

lines[].skuId integer

The SKU of the order line this entry names. Name a line by skuId or by lineRef. When the SKU is on more than one line the command can still act on, the command answers ORDER_LINE_AMBIGUOUS with the candidate lineRefs; name the line by one of them. Supply exactly one of lineRef and skuId.

Constraints: exclusive minimum: 0

lines[].quantity integer

The number of units.

Constraints: exclusive minimum: 0 Example 1

reason string

Constraints: minimum length: 1; maximum length: 1000 Example Ordered the wrong printing

Response

201

The pending cancellation request.

Response body: CancellationRequestResponse

success boolean required

Whether the operation completed as requested.

Constraints: allowed values: true Example true

data CancellationRequest required

The operation or event payload.

Show child fieldsHide child fields

data.id string required

The cancellation request id (cnr_…), stable for the life of the request (STABLE).

Example cnr_8d3f2a61b0c94e7f9a15c2d48e6b7031

data.order_id string required

The order the buyer asked to cancel (STABLE).

Example ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW

data.status string required

pending until it is answered. honored: a cancellation covered it. declined: the seller refused it, with resolution_note. withdrawn: the buyer took it back (STABLE).

Constraints: allowed values: pending, honored, declined, withdrawn Example pending

data.reason string or null required

The buyer's own words, or null when they gave none (STABLE).

Example Ordered the wrong printing

data.resolution_note string or null required

The decline reason the buyer is shown. Null unless status is declined (STABLE).

Example null

data.created_at string required

When the buyer opened the request (STABLE).

Constraints: format: date-time Example 2026-09-04T19:01:12.000Z

data.resolved_at string or null required

When the request was honored, declined or withdrawn. Null while it is pending (STABLE).

Constraints: format: date-time Example null

data.lines array of object or null required

The lines the buyer asked to cancel, or null when they asked to cancel the whole order (STABLE).

Show child fieldsHide child fields

data.lines[].line_ref string or null required

The purchase line the buyer asked to cancel, the same line_ref the order carries. Null only on a request recorded before line refs existed.

Example oln_1f0c8a4d7e2b45c9a1d6f3b8e07c9241

data.lines[].sku_id integer required

The SKU now on that line (STABLE).

Example 14602

data.lines[].quantity integer

How many units the buyer asked to cancel. Omitted means the whole line (STABLE).

Constraints: exclusive minimum: 0 Example 1

Errors

Errors return a MarketplaceError body, except HTTP 413, 500 (ApiError). Error codes explains both error bodies and lists every code.

400 INVALID_REQUEST IDEMPOTENCY_KEY_REQUIRED ORDER_LINE_AMBIGUOUS UNSUPPORTED_API_VERSION
Invalid command body, missing/invalid UUID Idempotency-Key, or a skuId on more than one line the command can still act on (ORDER_LINE_AMBIGUOUS, with the candidate lineRefs in details). Unknown or retired API-version override (UNSUPPORTED_API_VERSION).
Do this: Correct the request fields and supply a UUID Idempotency-Key. For ORDER_LINE_AMBIGUOUS, name that line by one of the lineRef values in details. Keep the same key when retrying the same command. For UNSUPPORTED_API_VERSION, choose a supported version from the API versioning guide.
401 UNAUTHORIZED
Missing or invalid marketplace API key (UNAUTHORIZED).
Do this: Send the marketplace API key for this seller as a Bearer token, then retry.
403 SUBSCRIPTION_EXCLUDES_ORDERS
The platform's subscription is inventory, which does not include orders (SUBSCRIPTION_EXCLUDES_ORDERS). Only orders and both subscriptions read and act on orders.
Do this: Do not retry. Ask Snapcaster to change the platform subscription to orders or both if the platform should handle orders.
404 ORDER_NOT_FOUND
No order matches this id for the authenticated seller (ORDER_NOT_FOUND). Another seller's order also returns 404, so the response does not reveal whether it exists. An order of this seller that no test purchase of this seller created also returns 404 (ORDER_NOT_FOUND): the sandbox buyer acts only on orders from POST /sandbox/test-purchases.
Do this: Use an order_id from GET /sandbox/test-purchases/{ref} for this seller.
409 IDEMPOTENCY_CONFLICT REQUEST_IN_PROGRESS REQUEST_ALREADY_OPEN CANCELLATION_REQUEST_LIMIT_REACHED
IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. REQUEST_ALREADY_OPEN when a cancellation request is already pending on the order. CANCELLATION_REQUEST_LIMIT_REACHED when the order already had three.
Do this: For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For REQUEST_ALREADY_OPEN, decline the pending request first. For CANCELLATION_REQUEST_LIMIT_REACHED, use another test purchase.
413 PAYLOAD_TOO_LARGE
The body is larger than this route accepts (PAYLOAD_TOO_LARGE).
Do this: Send a smaller body and retry.
422 CANCELLATION_NOT_ALLOWED
The buyer could not ask for this cancellation (CANCELLATION_NOT_ALLOWED): the order has shipped, or a line has fewer units left to cancel than asked.
Do this: Ask before you mark the order shipped, or name fewer units.
500 INTERNAL_ERROR
An unexpected failure (INTERNAL_ERROR).
Do this: Retry with bounded retries and jitter. If the failure persists, contact Snapcaster with the X-Correlation-ID response header.
503 TEST_PURCHASE_NOT_AVAILABLE
This deployment cannot act as the sandbox buyer right now (TEST_PURCHASE_NOT_AVAILABLE): it is not the sandbox, its payments are not in test mode, or its sandbox buyer is missing.
Do this: Call the sandbox API. If this persists there, contact Snapcaster with the X-Correlation-ID response header.

Have the sandbox buyer ask to cancel an order

Example

Endpoint

Request

Path parameters

Headers

Request body

Response

201

Errors

Related

Operations

Concepts

Changelog