partner
POST /v1/partner/orders/{orderId}/cancel
Cancel an order of yours that has not been fulfilled.
Authentication
Send an API key as a bearer token. The key must carry the partner.domains permission; a key without it is refused with 403, not 404.
This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/partner/orders/{orderId}/cancel \
-H "Authorization: Bearer zdk_live_…"Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
Stops an order you placed that has not been paid for and not been fulfilled — the stale rows left behind by verification and abandoned checkouts. Requires partner.domains. It never moves money. An order that has been paid is refused, not refunded: a refund is a separate, deliberate conversation. This is enforced by the order lifecycle itself, which has no transition from a paid state to a cancelled one, and not merely by this endpoint. It is not a subscription control. It cannot end a subscription, stop a renewal or tear down anything already provisioned. A verb that did both is how somebody eventually ends a paying customer's hosting while meaning to tidy a test order. It is idempotent. Cancelling an order that is already cancelled is a 200 carrying the current state, not a refusal, so a retry after a timeout is safe. Refusals are machine-readable under error.details[].code — error.code is the HTTP class and is not what you branch on: - not_yours — the order exists in a customer's org you can reach, but you did not place it (it is the customer's own, or another partner's). Alert your staff; it means a reference has been crossed somewhere on your side. - already_paid — money has moved. This is a refund conversation, not a cancellation. An order that is mid-fulfilment reports this too: the money is the harder half to undo. - already_fulfilled — at least one line has been delivered. A registered domain cannot be un-registered, so the whole call is refused rather than half-applied — an order whose state did not describe reality would fail your reconciliation for ever. When a line is the cause, that detail entry carries field: "lines" and names the domain in its own domain key. Branch on domain, never on the text of message: the sentence is translated and its wording is not part of this contract. An order id that does not exist, or one you have no reach into at all, is a 404 carrying details[].code = unknown_reference. The two cases are deliberately indistinguishable: telling you that an id exists but is out of your reach would report on other tenants' data.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
orderId (path) | string | Yes | Our order id, as returned in order_id when the order was placed — not your own reference. Keyed this way deliberately: it works for every order that already exists,… |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
order_id | string | Yes | — |
human_ref | string | Yes | The reference the payment page returns to you as ?order=. |
pay_url | string | No | Only in the response that placed (or replayed) the order: the hosted page the customer pays on. It carries a secret that is stored nowhere — treat it as one. |
pay_expires_at | string | No | — |
org_id | string | Yes | — |
status | string | Yes | pending_payment for a freshly placed order; afterwards the order's lifecycle (paid, fulfilling, completed, partially_fulfilled, canceled, …). |
currency | string | Yes | — |
subtotal_minor | integer | Yes | — |
tax_minor | integer | Yes | — |
total_minor | integer | Yes | — |
lines | PartnerOrderLine[] | Yes | — |
Errors this endpoint can return
401 · 403 · 404 · 422 · 429