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>"
}
}Returning online is retired: contact support
Devices can no longer be returned online. Since 2026-10-09 this route answers 409 wrong_state for every order that has not already ended, whatever the device, with a message giving the support address, and the body names the state the order is in. Nothing is asked of the payment provider, nothing is changed and nothing is refunded. Contact support and our team will help. A Cloud phone keeps its paid period, and POST /v1/fulfilments/{id}/cancel-renewal stops its next charge.
AN ORDER THAT HAS ALREADY ENDED answers 200 with alreadyDone: true, so a repeated press is told the truth rather than refused. A repeat within 24 hours of an earlier successful return is answered with that first answer, unchanged, and carries Idempotent-Replayed: true. Send no Idempotency-Key here; this route does not read one.
ADMIN, AND A SIGNED-IN PRINCIPAL ONLY. An API key is refused before the order is read, as before.
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_ or puk_ 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.
Response
The order had already ended (alreadyDone: true).
What ending an order did.