Cancel an order, or quantities on it

post

https://api.protectplus.io/orders/{order_number}/cancel

Cancel a whole platform: "custom" order, or individual quantities on
it, before it ships.

Cancellation has its own operation rather than being inferred from a
PUT. Dropping a line from a PUT body is not a cancellation and
never has been — it would destroy the line identity that returns and
claims are attached to, and it leaves the checks below nowhere to run.

Cancellations are final. There is no un-cancel.

Whole order or part of it

Omit lines to cancel the entire order. Supply lines to cancel
specific quantities — the order stays active while any live quantity
remains. cancelled_quantity is the cumulative total for a line,
not the increment for this request.

When a cancellation is refused

Situation	Result
An open or approved claim exists on the order (or on a line you are cancelling)	`409 CLAIM_EXISTS`
A line has an active return	`409 LINE_HAS_ACTIVE_RETURN`
The order has already shipped	`409 ORDER_ALREADY_SHIPPED`
We cannot reach the returns service to check	`503 RETURNS_CHECK_UNAVAILABLE` — retry
The order is already cancelled	`200`, nothing changes
`protection_cost_delta` exceeds the fair share for the quantity cancelled	`422 PROTECTION_DELTA_DISPROPORTIONATE`
The order has already been invoiced	Allowed — the credit lands on your next invoice

A cancellation is refused rather than partially applied: if you get a
4xx or 5xx, nothing was changed.

Protection fees

protection_cost_delta is the reduction in the protection fee,
apportioned by you and sent as a negative number. The order's own
protection_cost never changes — reductions are recorded against
the cancellation. A later PUT must therefore still send the
original protection_cost; sending the reduced figure is rejected
with 409 PROTECTION_IMMUTABLE.

How large a reduction may be

A reduction must be proportional to the value you are cancelling:

max reduction = charged protection fee x (value cancelled / order value)

Both sides are cumulative — lines carries cumulative quantities, so
the ceiling is measured against everything reduced on the order so far,
not this request alone. A stated figure within max($0.10, 1%) of the
ceiling is accepted exactly as sent; beyond that the whole request is
rejected with 422 PROTECTION_DELTA_DISPROPORTIONATE and nothing is
cancelled — we never reduce by a different amount than you asked for.
The response carries max_allowed, so a rejected request can be
corrected and resent.

While any quantity remains live on the order the remaining fee cannot
fall below $1.95; only cancelling the whole order releases the fee
entirely.

Example. A $9.00 fee on an order of three equally-priced items.
Cancelling one item allows at most $3.00. A stated -9.00 is rejected;
-3.00 through -3.10 is accepted as sent.

Retries

An Idempotency-Key (UUID) header is required when you send lines,
and optional for a whole-order cancel.

Quantities are cumulative and two partial cancels on one order are
legitimately two events, so a retry without a key would be recorded as a
second cancellation and credited twice. Omitting it on a partial cancel
returns 422 IDEMPOTENCY_KEY_REQUIRED.

A whole-order cancel is safe without one — an order can only move to
cancelled once — but sending a key still gives you an exact replayed
response instead of a fresh evaluation.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

order_number

string

required

Your order number, as supplied when the order was created.

Body Params

Request body for POST /orders/{order_number}/cancel — cancel a whole order, or individual quantities on it, before it ships.

Cancellation has its own operation rather than being inferred from a PUT. Dropping a line from a PUT body is NOT a cancellation and never has been: it would destroy the line identity that returns and claims are attached to, and it gives the preconditions below nowhere to run.

Cancellations are final. There is no un-cancel, and cancelled_quantity only ever grows.

Whole order or part of it. Omit lines to cancel the entire order. Supply lines to cancel specific quantities; the order itself stays active while any live quantity remains.

Preconditions. The request is refused with 409 when the order (or a targeted line) has an open claim, has an active return, or has already shipped. An order that is already cancelled returns 200 and changes nothing, so a retry is always safe. An order that has already been invoiced IS cancellable — the protection credit is applied to your next invoice rather than the one already issued.

Protection. protection_cost_delta is the reduction in the protection fee, apportioned by you and expressed as a negative number. The order's own protection_cost never changes: reductions are recorded against the cancellation, not by rewriting the order, so a later PUT must still send the ORIGINAL protection_cost. Sending the reduced figure is rejected with 409 PROTECTION_IMMUTABLE.

Later PUTs. The cancellation is recorded here, not in the order's figures, so don't take the cancelled units out of them: keep sending each cancelled line's quantity, unit_price and line_total as ordered, and leave the cancelled units in amounts.subtotal. A PUT that restates a cancelled line, or moves subtotal without the lines (lowering it by the cancelled units, say), gets the order flagged, so its claims are paid by the fallback. Adding, removing or re-pricing an item that nothing was cancelled on is not flagged when its line and subtotal move together (see PUT /orders/{order_number}).

An Idempotency-Key (UUID) request header is REQUIRED when lines is supplied, and optional (but recommended) for a whole-order cancel. Quantities are cumulative and two partial cancels on one order are legitimately two separate events, so a retry without a key would be recorded as a second cancellation and credited twice. A whole-order cancel needs no key to be safe — an order can only move to cancelled once — but sending one still gives you an exact replayed response. Omitting it on a partial cancel is rejected with 422 IDEMPOTENCY_KEY_REQUIRED.

cancelled_at

date-time

When the cancellation happened in your system (ISO 8601 / RFC 3339, UTC). Defaults to the time the request is received. Send a stable value on retries — it forms part of the de-duplication key when no Idempotency-Key header is supplied.

lines

array of objects

length ≥ 1

The lines to cancel quantities on. Omit this field entirely to cancel the whole order. Supplying this field makes an Idempotency-Key header mandatory. An empty array is rejected rather than treated as a whole-order cancel, because it almost always means a client-side filter removed everything — and a cancellation cannot be undone.

lines

protection_cost_delta

number

≤ 0

The reduction in the protection fee caused by this cancellation, apportioned by you. Zero or negative — a positive value is rejected rather than reinterpreted, so a sign error surfaces instead of being silently negated.

Across all cancellations on an order these may not sum past the original protection_cost; a request that would take them past it is rejected with 422 PROTECTION_DELTA_EXCEEDS_ORIGINAL.

Omit or send 0 for an unprotected order.

reason

string

length ≤ 500

Why the order or lines were cancelled. Free text, stored on the cancellation record and shown in the Get Plus admin. Not interpreted by Get Plus.

Headers

Idempotency-Key

uuid

Required when lines is supplied; optional for a whole-order
cancel. Makes a retry safe. Omitting it on a partial cancel returns
422 IDEMPOTENCY_KEY_REQUIRED. (Marked optional here because it is
conditional on the body — OpenAPI cannot express that on a header.)

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200Cancellation applied — or the order was already cancelled, in which case data.already_cancelled is true and nothing changed.

401Missing, invalid, expired, or revoked JWT. Tokens expire 60 minutes after issuance — if detail is "token expired", re-mint via POST /auth/v1/token and retry with the new bearer.

404No such order for this store.

409Refused by a precondition — CLAIM_EXISTS, LINE_HAS_ACTIVE_RETURN, or ORDER_ALREADY_SHIPPED. The code says which. Also IDEMPOTENCY_IN_PROGRESS: an earlier request with this Idempotency-Key is still running. Retry the same request shortly rather than minting a new key.

429Rate limited. This route is metered like the rest of /orders/*; Retry-After says how long to wait.

502The orders service could not be reached, or answered with an error of its own. Nothing was cancelled — safe to retry.

503RETURNS_CHECK_UNAVAILABLE — we could not confirm whether the order has an active return, so nothing was cancelled. Safe to retry.

504The orders service did not respond in time. Nothing was cancelled — retry with the SAME Idempotency-Key, which is what makes the retry safe if the original did in fact apply.