Cancel orders and answer requests

After checkout, an order changes when your platform cancels or refunds it, when a buyer asks to change it, or when the seller cannot ship some lines as sold. Every command on this page takes a UUID Idempotency-Key, which you reuse as Retry commands safely says. Cancellation request and change request events move no stock, so answer 2xx once you have stored them. A missed one shows up in your next syncToken poll, and its request list shows its status.

Cancel an order before shipping with POST /orders/{orderId}/cancel. After shipping, use POST /orders/{orderId}/refunds, which can refund the same order more than once. To act on only some lines, name each one by skuId or by lineRef, from the order line’s sku_id or line_ref. You need lineRef only when one SKU is on more than one line that still has units to cancel or refund. Naming such a SKU by skuId returns HTTP 400 ORDER_LINE_AMBIGUOUS with the candidate lineRef values in details.

Snapcaster sends order.cancelled or order.refunded for every cancellation and refund, including the ones your platform requested. Reconcile them on each line’s line_ref, and move stock by the stock change table.

You name lines, never an amount. Each entry in the order’s cancellations and refunds reports the money it returned in its payment_refund, which is made of these parts.

The seller’s side removed the cards when your platform cancels or refunds on its own, or when the buyer answers a fulfillment report. The buyer does not get the purchase fee share back when they asked for the removal themselves, through an accepted cancel_lines change request or a cancellation that covers their pending cancellation request. For example, cancelling a 325-cent card from an order with no shipping charge and no tax returns 336 cents, 11 of them purchase fee.

A buyer asks for a change with either a cancellation request or a change request, and no single call lists both kinds.

• Every GET /orders/{orderId} and GET /orders response carries the order’s pending cancellation requests in pending_cancellation_requests.
• GET /orders/{orderId}/change-requests lists the order’s change requests, and a pending buyer request among them has status: pending and the kind address_change or cancel_lines.

Order additions are switched off, so GET /orders/{orderId}/addition-requests never lists a buyer request to add cards.

A buyer can ask to cancel an order, or some of its lines, before it ships. Snapcaster sends order.cancellation_request.created, and the request appears in the order’s pending_cancellation_requests and in GET /orders/{orderId}/cancellation-requests. Each line of a request carries line_ref, sku_id, and an optional quantity, and null lines means the whole order.

To honor a request, cancel the lines it names with POST /orders/{orderId}/cancel, which resolves every pending request it covers. To refuse, send POST /orders/{orderId}/cancellation-requests/{requestId}/decline with a reason, which Snapcaster emails to the buyer. Either answer sends order.cancellation_request.resolved with outcome set to honored or declined. If the buyer takes the request back, Snapcaster sends order.cancellation_request.withdrawn and the order ships as sold. In the sandbox, raise one on an order from your test purchase with POST /sandbox/orders/{orderId}/cancellation-requests.

A buyer can ask to ship an order to another address, or to remove some of its lines or end it. Snapcaster sends order.change_request.created, and GET /orders/{orderId}/change-requests lists every change request on the order with its status. An order has at most one pending change request at a time. An address_change carries the new address and the previous_address. A cancel_lines request names its lines, and its amount_cents is the refund that accepting it returns. In the sandbox, raise either kind on an order from your test purchase with POST /sandbox/orders/{orderId}/change-requests.

To accept, send POST /orders/{orderId}/change-requests/{requestId}/accept, and Snapcaster applies the change right away. Accepting an address change updates ship_to, restarts address verification, and sends order.updated with reason address_corrected. Accepting a removal cancels the lines and sends order.cancelled if the order has not shipped, or refunds them and sends order.refunded if it has. After shipping, send restock: true if the removed cards came back into your stock, since it defaults to false. The refund is amount_cents, which keeps back the purchase fee like every removal the buyer asked for.

To refuse, send POST /orders/{orderId}/change-requests/{requestId}/decline and ship the order as sold. The decline takes no reason, because the seller explains it in the order’s support conversation, which the change request opened or joined, from its Snapcaster dashboard. Either answer emails the buyer and sends order.change_request.resolved with outcome set to accepted or declined. Answering a request that is no longer pending returns HTTP 409 ORDER_CHANGE_REQUEST_NOT_PENDING with the request’s status in details.

A request can also end without your answer. The buyer can withdraw it (withdrawn). Shipping, cancelling or refunding the order voids a pending request (voided), and so does correcting the address while an address change is pending. Each of these endings sends order.change_request.resolved.

The same list and events carry fulfillment_report requests, which are the seller’s own reports. The buyer answers those, so accepting or declining one returns HTTP 422 ORDER_CHANGE_REQUEST_NOT_ALLOWED.

When the seller cannot ship some lines as sold, file a fulfillment report with POST /orders/{orderId}/change-requests before the order ships. Name each affected line by lineRef or skuId and give it an action. A remove line takes units off the order, and quantity removes only some of them. A substitute line replaces the whole remaining line with another printing of the same card, and takes substituteSkuId and creditCents, the credit per unit the buyer gets back.

{
  "kind": "fulfillment_report",
  "payload": {
    "lines": [
      {
        "lineRef": "oln_1f0c8a4d7e2b45c9a1d6f3b8e07c9241",
        "action": "substitute",
        "substituteSkuId": 363348,
        "creditCents": 100
      }
    ],
    "note": "Our near mint copy was damaged; we can send a lightly played one."
  }
}

The substitute must be another SKU of the line’s catalog product that the seller lists live, with stock for the whole line, and not a SKU already on the order. GET /orders/{orderId}/substitute-candidates lists the SKUs that qualify for one line, each with its external_ref, available and unit_price. Snapcaster holds nothing for a substitute until the buyer accepts, and checks its stock again then. A substitute that breaks a rule, a partial quantity on a substitute line, or removals that cover every remaining unit return HTTP 422 ORDER_CHANGE_REQUEST_NOT_ALLOWED. To remove everything, cancel the order instead. An ambiguous skuId returns ORDER_LINE_AMBIGUOUS, as it does for a cancellation.

Snapcaster then emails the buyer and sends order.change_request.created. The optional note, up to 500 characters, appears in Snapcaster’s emails about the report and on the buyer’s order page. The optional message, up to 10,000 characters, goes into the order’s support conversation, where the seller reads the buyer’s replies in its Snapcaster dashboard.

Only the buyer answers the report, by accepting it, having every affected line removed instead, or cancelling the order. Each answer sends order.change_request.resolved with its outcome. An accepted report that only removes units sends order.cancelled. An accepted substitution moves the hold from the original line to the substitute, refunds the credit, and sends order.updated with reason line_substituted, which Substituted lines covers. Until the buyer answers, you can take the report back with POST /orders/{orderId}/change-requests/{requestId}/withdraw, which sends order.change_request.resolved with outcome set to withdrawn and emails no one.

In the sandbox, answer your own report as the buyer with POST /sandbox/orders/{orderId}/change-requests/{requestId}/answer, and set answer to accept, remove_instead or cancel_order. Act as the sandbox buyer shows how to set up a substitution there.