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 (OpenAPI 3.1 at /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":"..."}'
{"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 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):

{"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. A receive with "comp": true records free units at no cost, worth comp_value_cents each (default the item's unit cost); movements return comp_value_cents (null when not comp).
  • 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: 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: 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: 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.

Updated · View as Markdown · Question not answered?