---
title: "Cancel before it reaches a supplier"
method: POST
path: "/v1/orders/{order_id}/cancel"
tags: ["Orders"]
---

# Cancel before it reaches a supplier

`POST /v1/orders/{order_id}/cancel`

## Request

- Base URL: `https://api.placementapi.com`
- URL: `https://api.placementapi.com/v1/orders/{order_id}/cancel`
- Auth: HTTP bearer

Pulls an order back and refunds it in full, in the same statement. Orders are batched to suppliers each morning, so this is the window in which a mistake is cheaply reversible. Requires the `order` scope.

## Path parameters

- `order_id` string, required

## Response `200`

OK

- object
  - `order_id` string
  - `status` 'cancelled'
  - `credits_returned` integer

## Other responses

- `401`: Missing, malformed or revoked Bearer credential: `{ error: "unauthorized" }`.
- `403`: `insufficient_scope` when the key lacks the `order` scope; `customer_key_required` when the operator token is used where a customer must be attributable.
- `404`: `not_found`: no cancellable order with that id (including another customer's).
- `409`: `already_submitted`: the order has reached the supplier, so it can no longer be cancelled before fulfilment. Nothing is filed with a supplier automatically; a customer can ask us to pursue a supplier recovery review at hello@placementapi.com, and credits are then returned once we have recovered from the supplier and their refund window plus the account grace period have run, or earlier as a goodwill decision.
- `503`: `server_misconfigured` when the store is not configured; `upstream_unfunded` when the measurement provider's prepaid balance is exhausted (fresh profiles, gap maps and SERPs pause; cached results and catalogue are unaffected); `upstream_unavailable` on a provider error; `payments_unavailable` when card payments are not configured.

---

[API](https://skmtc.dev/placementapi/apis/placement-api.md) · [All operations](https://skmtc.dev/placementapi/apis/placement-api/llms.txt) · [OpenAPI document](https://skmtc.dev/placementapi/apis/placement-api/revisions/fc4e7866eaf7?raw)