Have the sandbox buyer ask for a change

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

Sandbox only: the production API does not serve this operation. Snapcaster's sandbox buyer asks the seller for a change to an order, exactly as a buyer does from their order page: an address_change to another address in the same province before the order ships (a test purchase ships to Vancouver, BC, so send another BC address), or a cancel_lines removal of some or all of its cards. It works only on an order from this seller's own test purchase; any other order returns 404 ORDER_NOT_FOUND. Snapcaster opens the order's support conversation if none is open, emails the seller and sends order.change_request.created, the same as for a real buyer. Answer it with POST /orders/{orderId}/change-requests/{requestId}/accept or /decline. 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: Change the address

curl --request POST \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/sandbox/orders/ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW/change-requests' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header 'Content-Type: application/json' \
  --data '{
  "kind": "address_change",
  "payload": {
    "address": {
      "line1": "555 Granville St",
      "line2": "Unit 4",
      "city": "Vancouver",
      "province": "BC",
      "postal_code": "V6C 1T2",
      "country": "CA"
    }
  }
}'

$(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 address change

{
  "success": true,
  "data": {
    "id": 381,
    "order_id": "ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW",
    "kind": "address_change",
    "status": "pending",
    "proposed_by_party": "buyer",
    "created_at": "2026-09-04T19:01:12.000Z",
    "resolved_at": null,
    "lines": null,
    "amount_cents": null,
    "note": null,
    "credits": null,
    "address": {
      "line1": "555 Granville St",
      "line2": "Unit 4",
      "city": "Vancouver",
      "province": "BC",
      "postal_code": "V6C 1T2",
      "country": "CA"
    },
    "previous_address": {
      "line1": "123 Test Street",
      "line2": null,
      "city": "Vancouver",
      "province": "BC",
      "postal_code": "V6B 1A1",
      "country": "CA"
    }
  }
}

Endpoint

Environment	URL
Sandbox	`https://api-sandbox.snapcaster.ca/api/v1/marketplace/sandbox/orders/{orderId}/change-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

Request body (application/json): CreateBuyerOrderChangeRequestBody

kind string required

Constraints: allowed values: cancel_lines, address_change Example address_change

payload object required

Constraints: additional properties are not allowed

Show child fieldsHide child fields

payload.lines array of object conditional

Required when kind is cancel_lines. The subset at the (order × SKU) grain the termination commands use; quantity omitted means the line’s whole remaining quantity, a smaller quantity removes that many units. Every remaining unit at once is the full-order termination: the BUYER may ask for it (the seller still grants or declines), the SELLER may not - their full cancel is unilateral, so they run it directly.

Constraints: minimum items: 1

Show child fieldsHide child fields

payload.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}$

payload.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

payload.lines[].quantity integer

The number of units.

Constraints: exclusive minimum: 0

payload.address object conditional

Required when kind is address_change.

Constraints: additional properties are not allowed

Show child fieldsHide child fields

payload.address.line1 string required

The street address.

Constraints: minimum length: 1; maximum length: 255 Example 555 Granville St

payload.address.line2 string or null

The unit, suite, or second address line, if supplied.

Constraints: maximum length: 255 Example Unit 4

payload.address.city string required

The city in the shipping address.

Constraints: minimum length: 1; maximum length: 255 Example Vancouver

payload.address.province string required

The Canadian province or territory in the delivery address.

Example BC

payload.address.postal_code string required

The Canadian postal code in the delivery address.

Example V6C 1T2

payload.address.country string required

Constraints: allowed values: CA Example CA

message string

An optional note threaded on the ticket the request rides.

Constraints: minimum length: 1; maximum length: 10000

Response

201

The pending change request, proposed_by_party: buyer.

Response body: ChangeRequestResponse

success boolean required

Whether the operation completed as requested.

Constraints: allowed values: true Example true

data ChangeRequest required

The operation or event payload.

Show child fieldsHide child fields

data.id integer required

The change request id, stable for the life of the request and the {requestId} of its answers (STABLE).

Constraints: exclusive minimum: 0 Example 381

data.order_id string required

The order the request is about (STABLE).

Example ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW

data.kind string required

address_change: the buyer asks to ship to address instead of previous_address. cancel_lines: the buyer asks to remove lines, or every remaining line to end the order. fulfillment_report: the seller reports that lines cannot ship as sold, and the buyer answers it (STABLE).

Constraints: allowed values: cancel_lines, fulfillment_report, address_change Example address_change

data.status string required

pending until it is answered; a request has no deadline. accepted: the change ran. declined: the answering party refused it and nothing changed. withdrawn: the party who raised it took it back. voided: the order shipped, was cancelled or refunded, its address was corrected, or Snapcaster closed the support conversation the request belonged to, before anyone answered. removed_instead and order_cancelled are the buyer answers to a fulfillment_report that remove every affected line or end the order. expired appears only on requests from before requests stopped lapsing (STABLE).

Constraints: allowed values: pending, accepted, removed_instead, order_cancelled, declined, withdrawn, voided, expired Example pending

data.proposed_by_party string required

Who raised it. The seller answers a buyer request by accepting or declining it; the buyer answers a seller request (STABLE).

Constraints: allowed values: buyer, seller, operator, system Example buyer

data.created_at string required

When the request was raised (STABLE).

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

data.resolved_at string or null required

When the request left pending; null while it is pending (STABLE).

Constraints: format: date-time Example null

data.lines ChangeRequestLine[] or null required

The lines a cancel_lines or fulfillment_report request names; null on an address_change (STABLE).

Show child fieldsHide child fields

data.lines[].line_ref string required

The purchase line the request names, the same line_ref the order carries (STABLE).

data.lines[].name string required

The line title, or SKU <sku_id> when the catalog had none (STABLE).

data.lines[].quantity integer required

How many units of the line the request covers (STABLE).

Constraints: exclusive minimum: 0

data.lines[].sku_id integer required

The SKU the line was sold as (STABLE).

data.lines[].product_id integer or null required

The product that SKU belongs to; null on a request recorded before it was kept (STABLE).

data.lines[].ordered object required

The card the buyer ordered, as the request recorded it. A fact the request never recorded is null (STABLE).

Show child fieldsHide child fields

data.lines[].ordered.name string or null required: The card title (STABLE).
data.lines[].ordered.set string or null required: The set the printing belongs to; null when it was never recorded (STABLE).
data.lines[].ordered.language string or null required: The printing language; null when it was never recorded (STABLE).
data.lines[].ordered.finish string or null required: The printing or finish, such as Foil; null when never recorded (STABLE).
data.lines[].ordered.rarity string or null required: The rarity; null when it was never recorded (STABLE).
data.lines[].ordered.condition string or null required: The condition grade; null when it was never recorded (STABLE).
data.lines[].ordered.collector_number string or null required: The collector number as the catalog states it, such as 161/302; null when never recorded (STABLE).

data.lines[].action string required

remove on every cancel_lines line and on a report line that removes units. substitute on a report line that ships a replacement named in substitute at a per-unit credit_cents. split on a report line whose units go several ways, listed in dispositions (STABLE).

Constraints: allowed values: remove, substitute, split

data.lines[].substitute ChangeRequestSubstitute or null required

The replacement on a substitute line; null on every other line (STABLE).

Show child fieldsHide child fields

data.lines[].substitute.listing_id integer required: Snapcaster's id for the seller listing offered in place of the line (STABLE).
data.lines[].substitute.sku_id integer required: The SKU the line ships as once the report is accepted (STABLE).
data.lines[].substitute.product_id integer required: The product, the same one the replaced line belongs to (STABLE).
data.lines[].substitute.external_ref string or null required: Your platform's reference on that listing when the report was filed; null when none was sent (STABLE).
data.lines[].substitute.name string or null required: The card title (STABLE).
data.lines[].substitute.set string or null required: The set the printing belongs to; null when it was never recorded (STABLE).
data.lines[].substitute.language string or null required: The printing language; null when it was never recorded (STABLE).
data.lines[].substitute.finish string or null required: The printing or finish, such as Foil; null when never recorded (STABLE).
data.lines[].substitute.rarity string or null required: The rarity; null when it was never recorded (STABLE).
data.lines[].substitute.condition string or null required: The condition grade; null when it was never recorded (STABLE).
data.lines[].substitute.collector_number string or null required: The collector number as the catalog states it, such as 161/302; null when never recorded (STABLE).
data.lines[].substitute.printing string or null required: The same fact as finish, under the catalog name (STABLE).

data.lines[].credit_cents integer or null required

The credit per unit on a substitute line, in cents; null on every other line (STABLE).

data.lines[].dispositions array of object or null required

On a split line, each portion in the order the seller listed them; null on every other line (STABLE).

Show child fieldsHide child fields

data.lines[].dispositions[].action string required

What happens to this portion (STABLE).

Constraints: allowed values: remove, substitute

data.lines[].dispositions[].quantity integer required

How many of the line units go this way (STABLE).

Constraints: exclusive minimum: 0

data.lines[].dispositions[].substitute ChangeRequestSubstitute or null required

The replacement on a substitute line; null on every other line (STABLE).

Show child fieldsHide child fields

data.lines[].dispositions[].substitute.listing_id integer required: Snapcaster's id for the seller listing offered in place of the line (STABLE).
data.lines[].dispositions[].substitute.sku_id integer required: The SKU the line ships as once the report is accepted (STABLE).
data.lines[].dispositions[].substitute.product_id integer required: The product, the same one the replaced line belongs to (STABLE).
data.lines[].dispositions[].substitute.external_ref string or null required: Your platform's reference on that listing when the report was filed; null when none was sent (STABLE).
data.lines[].dispositions[].substitute.name string or null required: The card title (STABLE).
data.lines[].dispositions[].substitute.set string or null required: The set the printing belongs to; null when it was never recorded (STABLE).
data.lines[].dispositions[].substitute.language string or null required: The printing language; null when it was never recorded (STABLE).
data.lines[].dispositions[].substitute.finish string or null required: The printing or finish, such as Foil; null when never recorded (STABLE).
data.lines[].dispositions[].substitute.rarity string or null required: The rarity; null when it was never recorded (STABLE).
data.lines[].dispositions[].substitute.condition string or null required: The condition grade; null when it was never recorded (STABLE).
data.lines[].dispositions[].substitute.collector_number string or null required: The collector number as the catalog states it, such as 161/302; null when never recorded (STABLE).
data.lines[].dispositions[].substitute.printing string or null required: The same fact as finish, under the catalog name (STABLE).

data.lines[].dispositions[].credit_cents integer or null required

The credit per unit for a substitute portion; null for a removal (STABLE).

data.amount_cents integer or null required

The refund, tax included, that accepting a cancel_lines request returns to the buyer, or the refund a fulfillment_report returns when the buyer accepts it. Fixed when the request was raised. Null on an address_change and on an order with no payment (STABLE).

Example null

data.note string or null required

The seller's note to the buyer on a fulfillment_report; null when none was given and on every other kind (STABLE).

Example null

data.credits object or null required

The refund behind each buyer answer to a fulfillment_report, fixed when it was raised; null on every other kind and on an order with no payment (STABLE).

Show child fieldsHide child fields

data.credits.accept_cents integer required: The refund if the buyer accepts the report; repeats amount_cents (STABLE).
data.credits.remove_instead_cents integer required: The refund if the buyer has every affected line removed instead (STABLE).
data.credits.cancel_order_cents integer required: The refund if the buyer ends the whole order instead (STABLE).

data.address OrderWebhookShippingAddress or null required

The shipping address an address_change asks for. Set only on an address_change; null on every other kind (STABLE).

Show child fieldsHide child fields

data.address.line1 string required

The street address.

Example 555 Granville St

data.address.line2 string or null required

The unit, suite, or second address line, if supplied.

Example Unit 4

data.address.city string required

The city in the shipping address.

Example Vancouver

data.address.province string required

The Canadian province or territory in the delivery address.

Example BC

data.address.postal_code string required

The Canadian postal code in the delivery address.

Example V6C 1T2

data.address.country string required

ISO 3166-1 alpha-2 country code.

Example CA

data.previous_address OrderWebhookShippingAddress or null required

The shipping address the order had when the address_change was raised. Set only on an address_change; null on every other kind (STABLE).

Show child fieldsHide child fields

data.previous_address.line1 string required

The street address.

Example 123 Test Street

data.previous_address.line2 string or null required

The unit, suite, or second address line, if supplied.

Example null

data.previous_address.city string required

The city in the shipping address.

Example Vancouver

data.previous_address.province string required

The Canadian province or territory in the delivery address.

Example BC

data.previous_address.postal_code string required

The Canadian postal code in the delivery address.

Example V6B 1A1

data.previous_address.country string required

ISO 3166-1 alpha-2 country code.

Example CA

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 ORDER_CHANGE_REQUEST_ALREADY_PENDING SUPPORT_CASE_CLOSED
IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. ORDER_CHANGE_REQUEST_ALREADY_PENDING when the order already has a pending change request, from either party; details carries its id. SUPPORT_CASE_CLOSED when Snapcaster closed the order's support conversation while the request was being opened.
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 ORDER_CHANGE_REQUEST_ALREADY_PENDING, answer or withdraw the pending request first. For SUPPORT_CASE_CLOSED, retry with a new key.
413 PAYLOAD_TOO_LARGE
The body is larger than this route accepts (PAYLOAD_TOO_LARGE).
Do this: Send a smaller body and retry.
422 ORDER_CHANGE_REQUEST_NOT_ALLOWED INVALID_TRANSITION SUPPORT_CASE_WINDOW_CLOSED
The buyer could not ask for this change, with the codes the buyer gets. ORDER_CHANGE_REQUEST_NOT_ALLOWED: the order is cancelled or refunded, or an address_change came after it shipped. INVALID_TRANSITION: a line has nothing left to remove. SUPPORT_CASE_WINDOW_CLOSED: the order is too old for a support conversation.
Do this: Do not retry the same body. Read the message, then change the request.
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 for a change

Example

Endpoint

Request

Path parameters

Headers

Request body

Response

201

Errors

Related

Operations

Concepts

Changelog