A valid request URL is required to generate request examples{
"id": "<string>",
"state": "cancelled",
"alreadyDone": true,
"deviceId": "<string>",
"leaseCut": true
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "not_found",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "admission_unavailable",
"message": "<string>"
}
}Cancel an order that has not arrived, and get all of it back
Ends an order that is still awaiting_provisioning and refunds the whole payment.
CANCEL OR RETURN, and the difference is whether anything was ever delivered. An order still awaiting provisioning is one where the shelf was empty when it settled: nothing arrived, so all of the money goes back and this is the route. An order that IS provisioned has been in your hands, and POST /v1/fulfilments/{id}/return is the route for that. Calling the wrong one answers 409 naming the state the order is actually in, rather than quietly doing the other thing.
PRESSING IT TWICE IS SAFE AND IS NOT AN ERROR, and you do not have to do anything to make it so: the key is derived from the order and the action, so every retry of one cancellation lands on the same one whether or not you send anything. Send no Idempotency-Key here; this route does not read one.
A REPEAT WITHIN 24 HOURS IS ANSWERED WITH THE FIRST ATTEMPT’S ANSWER, unchanged, and carries Idempotent-Replayed: true. After that the order is simply found already ended and answers 200 with alreadyDone: true. Either way the payment provider is asked for nothing, so a double-clicked button cannot produce a second refund. Two calls that arrive AT THE SAME TIME do not both proceed: one does the work and the other is told so with 409 idempotency_conflict and retryable: true.
ADMIN, AND A SIGNED-IN PRINCIPAL ONLY, the same rule the purchase has and for the reason turned around: if only an admin can commit the organisation to a subscription, only an admin can end one. An API key is refused, because undoing a purchase is not something a program should do while nobody is watching.
NOTHING IS RECORDED UNTIL THE PROVIDER HAS AGREED. If the refund cannot be arranged, the order is left exactly as it was and you are told to try again. An order marked cancelled with the money still taken would look like success from every screen, which is why the order of operations is this way round.
Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404.
A valid request URL is required to generate request examples{
"id": "<string>",
"state": "cancelled",
"alreadyDone": true,
"deviceId": "<string>",
"leaseCut": true
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "not_found",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "admission_unavailable",
"message": "<string>"
}
}Authorizations
The control surface credential. Send Authorization: Bearer <token>.
Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.
Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.
Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.
Path Parameters
The order id, as GET /v1/fulfilments reports it.
Response
The order is ended.
What ending an order did.
The order this answers about.
What the order is now. Always cancelled: both of these routes end an order.
cancelled TRUE when the order had already been ended before this call, so nothing was asked of the payment provider and no second refund was issued. Both cases answer 200. Pressing the button twice is not an error and must not read like one, and this is how a client tells them apart.
The device that went back, on a return. Null on a cancellation, where no device had been provided, and null on a repeated call.
Whether a session that was live at that moment was ended by this. False for the ordinary return of an idle device, and false on any deployment configured to let sessions expire on their own.