---
title: "update sales order"
method: PATCH
path: "/api/v1/sales/orders/{order_id}"
tags: ["orders"]
---

# update sales order

`PATCH /api/v1/sales/orders/{order_id}`

## Request

- Base URL: `https://api.app.tightly.io`
- URL: `https://api.app.tightly.io/api/v1/sales/orders/{order_id}`
- Auth: HTTP bearer

Changes what a person may change on an order Tightly owns: its ship date, its cancel date, your own reference, the warehouse it will ship from, and its lines. `lines` names only the lines you are changing, each by its `order_line_item_id` (as the read serves it) or by `variant_id` or `sku`. A `quantity` of 0 removes one, a `variant_id` the order does not carry adds one, and a line you do not name is left alone, so two people editing one order do not delete each other's work.

Allowed in `draft`, `open` and `allocated`, and it re-allocates. An order that came from a connected channel is never changed here; change it in the channel. An order whose fulfilment has been requested is refused `order_locked_for_fulfilment`, and the lock is the order's lifecycle alone: it stands from the moment the request is raised, whether the warehouse has been sent it, is still holding it queued, or failed to take it. A queued request may leave any second and a failed one may be retried, and either would carry the lines as they were before your change.

Read the date in that refusal as the day the request was RAISED. The sentence reads "was sent to <warehouse> on <date>", and the date it names is the order's `lifecycle_updated_at`, not the moment the warehouse was actually called, which is a separate stamp. cancel_sales_order is the one door that looks at what the warehouse holds: a cancel is allowed from `fulfilment_requested` while the request is queued or failed.

Scope: `orders:write`, which includes `orders:read`.

## Path parameters

- `order_id` string, required

## Headers

- `Tightly-Version` string
- `Idempotency-Key` string

## Request body

- PatchSalesOrderRequest
  - `cancel_date` string, nullable
  - `external_reference` string, nullable
  - `lines` PatchSalesOrderLineArg[], nullable
    - `order_line_item_id` string, nullable
    - `quantity` integer, required
    - `sku` string, nullable
    - `unit_price_cents` integer, nullable
    - `variant_id` string, nullable
  - `location_id` string, nullable
  - `requested_ship_date` string, nullable

## Response `200`

The order as it now stands. An allocated order the change leaves holding nothing, every line removed, reads `open`, the lifecycle of an order that holds nothing.

## Other responses

- `400`: A line names a product the order does not carry (`line_not_on_order`), a product Tightly does not know (`variant_unknown`), or a quantity below zero (`quantity_not_positive`); the warehouse named is not on file (`location_unknown`); a date is not written YYYY-MM-DD (`date_unreadable`).
- `401`: No usable key: malformed, unknown, revoked, expired or stopped.
- `403`: The key does not hold Orders (`scope_missing`), or is issued to one account and the record is not that account's (`account_mismatch`).
- `404`: No order with that id is on file.
- `409`: `channel_order_is_the_channels`, `order_locked_for_fulfilment`, `order_already_fulfilled`, `order_already_cancelled`.
- `429`: The key has spent its allowance for this minute. 600 reads and 120 writes a minute, counted per key, refused calls included. `Retry-After` says how long to wait.
- `503`: The database is briefly out of reach, which is what a failover or a full connection pool looks like from outside. Wait the seconds `Retry-After` names and send the request again. A read is safe to repeat. A write is not, because the connection was lost in the middle of it, so read the object back before sending it a second time. Branch on the status rather than on `code`, which is `POSTGRES_UNAVAILABLE` from one of the two seams that raise this and `SERVICE_UNAVAILABLE` from the other.

---

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