# REST API

A JSON API for your own software: items, stock movements, the order list and
purchase orders. The full reference, generated from the code, is at
[/api/docs](/api/docs) (OpenAPI 3.1 at [/api/docs.json](/api/docs.json));
this page is the short version.

## Getting access

1. The **Account Holder** opens Company → **Manage API access** and creates a
   **service account** (a name plus scopes), confirming with their second
   factor. The **client id** and **client secret** are shown once; store the
   secret in your integration's secret store.
2. Scopes: `inventory:read` (every GET) and `inventory:write` (everything that
   changes data; also needs an active subscription). Write implies read.
3. Administrators see the list, limits and the request log; only the Account
   Holder creates, rotates, re-scopes or revokes. Revoking stops a service
   account's tokens immediately.

## Tokens

Exchange the credentials for a bearer token (OAuth 2.0 client credentials):

```
curl -X POST https://sobocoo.com/api/v1/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"sbc_...","client_secret":"..."}'
```

```json
{"access_token":"eyJ...","token_type":"Bearer","expires_in":3600,"scope":"inventory:read inventory:write"}
```

Tokens last one hour. Send `Authorization: Bearer <access_token>` on every
request. A `401` with `WWW-Authenticate: Bearer` means the token is missing,
expired or revoked, or the company is suspended: get a new token. The token
endpoint also accepts a form body or HTTP Basic (`client_id:client_secret`).
Failed exchanges are throttled per IP and per client id.

## Rate limits

Each service account may make **1,000 requests per hour**, and all of a
company's accounts together **5,000 per hour**; [ask us](/contact) to raise
either. Every response carries:

| Header | Meaning |
|---|---|
| `RateLimit-Limit` | requests per hour in the tighter window |
| `RateLimit-Remaining` | requests left in it |
| `RateLimit-Reset` | seconds until it frees up |
| `X-RateLimit-Scope` | `client` or `company` |

Over the budget you get `429` with `Retry-After`. The token endpoint is not
counted.

## Errors

Every error is `application/problem+json` (RFC 9457):

```json
{"type":"about:blank","title":"Unprocessable Content","status":422,
 "detail":"The request has invalid fields.","code":"validation_failed",
 "errors":{"name":"Required."}}
```

`code` is stable; switch on it: `validation_failed`, `insufficient_stock`,
`invalid_movement`, `item_archived`, `duplicate_number`, `invalid_order`, `invalid_receipt`, `invalid_correction`,
`not_receivable`, `unknown_code`, `not_found`, `forbidden`, `invalid_token`,
`invalid_client`, `rate_limited`, `invalid_json`. A record from another
company is a `404`, never a `403`.

## Conventions

- Money is **integer cents** in the company's currency (`unit_cost_cents`,
  `price_cents`); times are ISO 8601 UTC (`2026-11-06T14:13:00Z`).
- Item lists are keyset-paginated: follow `links.next` / `links.prev`.
  Ledgers use `limit`/`offset` within a `from`/`to` range (default 90 days).
- `GET /api/v1/items/lookup?code=` takes what a scanner reads: a Sobocoo QR
  URL or code, a UPC/EAN, or a SKU.
- Movements: `receive`, `issue`, `sale` take a positive quantity; `adjust`
  takes the signed delta; `POST /items/{id}/count` sets a counted total. Put
  the supplier's PO or invoice number in `reference`: it is searchable in the
  [audit trail](/docs/audit-trail). A `receive` with `"comp": true` records
  [free units](/docs/stock-movements#free-comp-receipts) at no cost, worth
  `comp_value_cents` each (default the item's unit cost); movements return
  `comp_value_cents` (null when not comp).
- [Sites](/docs/sites): a service account sees every site that is not
  archived. Items and purchase orders carry their `site`; `GET /api/v1/sites`
  lists the ids. Lists (`items`, `movements`, `order-list`,
  `purchase-orders`) and `items/lookup` take `?site=` to cover one site.
  `POST /items` takes `site_id` (default: the default site); an item never
  changes site, and a purchase order's lines must all be at one site.
- [Vendors](/docs/ordering#vendors): orders carry `vendor` (`id`, `name`).
  `supplier` is kept for older integrations and is the vendor's current
  name (the same as `vendor.name`), or null when the order has no vendor.
  `GET /api/v1/vendors` lists the ids. Creating or updating an order takes
  `vendor_id` or a `supplier` name, which matches a vendor ignoring capitals
  or adds a new one; archived vendors are refused.
- [Tracking numbers](/docs/ordering#tracking-numbers): every order carries
  `tracking` (number, carrier, carrier's tracking URL, note). Create an
  order with a `tracking` list, or add one with
  `POST /purchase-orders/{id}/tracking` (`number`, optional `carrier`
  `ups` / `fedex` / `usps` / `dhl` / `other`, otherwise detected, and
  `note`), change its `carrier` (`null` detects it again) or `note` with
  `PATCH /purchase-orders/{id}/tracking/{trackingId}` (the number cannot
  change), and remove it with `DELETE /purchase-orders/{id}/tracking/{trackingId}`.
  A number already on an order is code `duplicate_tracking`.
  `GET /purchase-orders?tracking=` finds the order holding a number.
  `POST /purchase-orders/{id}/receive` takes `tracking` (the number as
  typed or scanned from the label) or `tracking_id` to mark that box
  received with the delivery; a number on another order is code
  `tracking_not_on_order`, one you do not have is `unknown_tracking`.
- [Correcting an order](/docs/ordering#correcting-an-order):
  `PATCH /purchase-orders/{id}/correct` changes what **Edit order** in the
  app changes, at any status, with the same rules and the same results in
  stock, the ledger and the audit trail. Send only what changes: a field
  left out keeps its value, and so does a line left out of `lines` or a
  line field left out of its object. Lines are `{line_id, ...}` with the
  line's own field names (`quantity_ordered`, `expected_unit_cost_cents`,
  `quantity_received`, `quantity_damaged`, `quantity_returned`,
  `actual_unit_cost_cents`, `return_reason`, `quantity_comp`,
  `quantity_comp_received`, `quantity_comp_damaged`) plus `remove: true`;
  counts are totals, not deltas. `fees`, when sent, replaces the whole fee
  list. `tracking` takes `{add: [...], remove: [ids]}`. The order number
  cannot change, and unknown fields are refused. A refused correction is
  code `invalid_correction` with the app's message; the response carries
  the updated order and `changed` (false when nothing changed).
- Everything a service account does is in the company's audit trail (actor
  *API: name*) and in the request log under API access (kept 90 days).

## Endpoints

| Area | Endpoints |
|---|---|
| Auth | `POST /api/v1/token`, `GET /api/v1/me` |
| Sites | `GET /api/v1/sites` |
| Vendors | `GET /api/v1/vendors` |
| Items | `GET /api/v1/items`, `GET /items/lookup`, `GET /items/{id}`, `POST /items`, `PATCH /items/{id}`, `POST /items/{id}/archive`, `/unarchive` |
| Stock | `GET /items/{id}/movements`, `POST /items/{id}/movements`, `POST /items/{id}/count`, `GET /api/v1/movements` |
| Order list | `GET/POST /api/v1/order-list`, `GET/PATCH /order-list/{id}`, `POST .../ordered`, `/received`, `/dismiss` |
| Purchase orders | `GET/POST /api/v1/purchase-orders`, `GET/PATCH /purchase-orders/{id}`, `PATCH .../correct`, `POST .../receive`, `/close`, `POST .../tracking`, `PATCH/DELETE .../tracking/{trackingId}` |

Full parameters, bodies and responses: [/api/docs](/api/docs).
