Decline an add-on request (not yet available)

POST /orders/{orderId}/addition-requests/{requestRef}/decline

Not yet available. Order additions are switched off in production and in the sandbox, so no buyer can ask for added cards and no offer can be sent: the lists answer eligibility.eligible: false with the reason feature_disabled, and sendOrderAdditionOffer answers 422 ORDER_ADDITION_NOT_ELIGIBLE. Do not build against this operation yet; the changelog announces when additions open. The example request shows the shape only and cannot succeed in the sandbox: sending an offer answers 422 ORDER_ADDITION_NOT_ELIGIBLE, and declining a request or withdrawing an offer answers 404 because none can exist. Decline a buyer's pending add-on request, with an optional note the buyer reads. Nothing else on the order changes: it ships as bought, and the buyer may ask again. Snapcaster sends order.addition_request.resolved with status: declined. To answer the request with priced cards instead, send an offer naming it in requestRef. Returns the declined request.

Example

These examples send requests to the sandbox.

Replace the example orderId and requestRef in the URL with your own.

Generated cURL request - Sandbox: Generated request

curl --request POST \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/orders/ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW/addition-requests/oar_5c1e9a7f3b2d48e6a0f4c8d1b7e3a925/decline' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header 'Content-Type: application/json' \
  --data '{}'

$(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 200: Declined request

{
  "success": true,
  "data": {
    "request_ref": "oar_5c1e9a7f3b2d48e6a0f4c8d1b7e3a925",
    "status": "declined",
    "lines": [
      {
        "sku_id": 14602,
        "product_id": 86,
        "quantity": 2,
        "name": "Abyssal Nightstalker",
        "set_name": "Portal Second Age",
        "condition": "Near Mint",
        "category_name": "Magic: The Gathering",
        "language": "English",
        "finish": "Normal",
        "collector_number": null,
        "rarity": "Uncommon"
      }
    ],
    "note": "Two more for my sideboard, please",
    "support_case_id": null,
    "created_at": "2026-09-04T19:01:12.000Z",
    "resolved_by_party": "seller",
    "resolved_at": "2026-09-04T19:20:41.000Z",
    "resolution_note": "Sold out of that printing"
  }
}

Endpoint

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

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

requestRef string required

The add-on request id (oar_…) from the list or a webhook.

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

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): DeclineOrderAdditionRequestBody

note string

A short reason the buyer reads beside the decline.

Constraints: minimum length: 1; maximum length: 1000

Response

200

The request, now declined.

Response body: OrderAdditionRequestResponse

success boolean required

Whether the operation completed as requested.

Constraints: allowed values: true Example true

data OrderAdditionRequest required

The operation or event payload.

Show child fieldsHide child fields

data.request_ref string required

The opaque public request id (oar_…) - the {requestRef} of the withdraw and decline paths.

Example oar_5c1e9a7f3b2d48e6a0f4c8d1b7e3a925

data.status string required

pending is the one open state. withdrawn is the buyer taking their own ask back; declined is the seller’s answer; offered means the seller ANSWERED it with a payable offer, whose own lifecycle carries on under addition-offers and which names this request. All three endings are one-way and change nothing else about the order.

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

data.lines OrderAdditionRequestLine[] required

The cards asked for, with enough canonical catalog identity frozen at the ask to say which PRINTING was meant - condition, finish, language, collector number - so a later catalog correction cannot change what was understood.

Show child fieldsHide child fields

data.lines[].sku_id integer required

The exact printing asked for. This is the identity; everything beside it is frozen from it.

Example 14602

data.lines[].product_id integer required

See Canonical catalog in Core concepts.

Example 86

data.lines[].quantity integer required

The number of units.

Example 2

data.lines[].name string or null required

Example Abyssal Nightstalker

data.lines[].set_name string or null required

Example Portal Second Age

data.lines[].condition string or null required

The normalized condition assigned to the card.

Example Near Mint

data.lines[].category_name string or null required

Example Magic: The Gathering

data.lines[].language string or null required

The language of the card printing.

Example English

data.lines[].finish string or null required

The catalog’s printing, under the name the order line snapshot uses.

Example Normal

data.lines[].collector_number string or null required

Example null

data.lines[].rarity string or null required

The rarity assigned to the card printing.

Example Uncommon

data.note string or null required

The buyer’s own words beside the ask; null when none was given.

Example Two more for my sideboard, please

data.support_case_id integer or null required

The support conversation the ask came out of, when there was one; null otherwise.

Example null

data.created_at string required

Example 2026-09-04T19:01:12.000Z

data.resolved_by_party string or null required

Who ended the ask - buyer on a withdrawal, seller on a decline. Null while pending.

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

data.resolved_at string or null required

Example 2026-09-04T19:20:41.000Z

data.resolution_note string or null required

The seller’s short reason on a decline, shown to the buyer beside the ending.

Example Sold out of that printing

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 UNSUPPORTED_API_VERSION
Invalid command body or missing/invalid UUID Idempotency-Key. Unknown or retired API-version override (UNSUPPORTED_API_VERSION).
Do this: Correct the request fields and supply a UUID Idempotency-Key. 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 ORDER_ADDITION_REQUEST_NOT_FOUND
Order additions are not yet available. No order matches this id for the authenticated seller (ORDER_NOT_FOUND), or no add-on request with this id is on the order (ORDER_ADDITION_REQUEST_NOT_FOUND). Another seller's order also returns 404.
Do this: Read GET /orders/{orderId}/addition-requests for the request ids on the order.
409 IDEMPOTENCY_CONFLICT REQUEST_IN_PROGRESS ORDER_ADDITION_REQUEST_NOT_PENDING
Order additions are not yet available. IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. ORDER_ADDITION_REQUEST_NOT_PENDING: the request was already withdrawn, declined or answered with an offer; details.status says which.
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_ADDITION_REQUEST_NOT_PENDING, read GET /orders/{orderId}/addition-requests; a request that is no longer pending needs no answer.
413 PAYLOAD_TOO_LARGE
The body is larger than this route accepts (PAYLOAD_TOO_LARGE).
Do this: Send a smaller body and retry.
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.

Decline an add-on request (not yet available)

Example

Endpoint

Request

Path parameters

Headers

Request body

Response

200

Errors

Related

Operations

Concepts

Changelog