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>"
}
}Give a device back and stop the meter
Ends a provisioned order. The device goes back, your ownership of it goes, and billing for it stops.
WHAT COMES BACK, AND WHY IT IS NOT THE WHOLE PAYMENT. You had the device and you used it. Cancelling an order that never arrived returns all of the money; returning one that did returns the part you have not used, computed by the payment provider from its own prices. This service states no amount, here or anywhere: an amount computed on this side would be a second opinion about a price it deliberately cannot read. Under pay-as-you-go billing there is nothing to prorate and this simply stops the meter, which is the whole of what returning means for something billed by the minute.
AN ORDER STILL AWAITING PROVISIONING cannot be returned: there is nothing to give back. That is 409, and POST /v1/fulfilments/{id}/cancel is the route.
A SESSION YOU ARE HOLDING RIGHT NOW may or may not be cut, and which of the two is a property of the deployment rather than of this call. leaseCut in the answer says what happened. Either way the device stops being yours immediately.
Idempotent, admin-only, and provider-first, exactly as cancelling is: see that route for all three. The key is derived here too, so this route reads no Idempotency-Key either, and the replay matters more here than it does on cancel, because a return’s answer names the device that came back and whether your lease was cut. A repeat within 24 hours gives you those again; after that it can only tell you the order ended.
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 device is back and 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.