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
- 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.
- Scopes:
inventory:read(every GET) andinventory:write(everything that changes data; also needs an active subscription). Write implies read. - 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 uselimit/offsetwithin afrom/torange (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,saletake a positive quantity;adjusttakes the signed delta;POST /items/{id}/countsets a counted total. Put the supplier's PO or invoice number inreference: it is searchable in the audit trail. Areceivewith"comp": truerecords free units at no cost, worthcomp_value_centseach (default the item's unit cost); movements returncomp_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/siteslists the ids. Lists (items,movements,order-list,purchase-orders) anditems/lookuptake?site=to cover one site.POST /itemstakessite_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).supplieris kept for older integrations and is the vendor's current name (the same asvendor.name), or null when the order has no vendor.GET /api/v1/vendorslists the ids. Creating or updating an order takesvendor_idor asuppliername, 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 atrackinglist, or add one withPOST /purchase-orders/{id}/tracking(number, optionalcarrierups/fedex/usps/dhl/other, otherwise detected, andnote), change itscarrier(nulldetects it again) ornotewithPATCH /purchase-orders/{id}/tracking/{trackingId}(the number cannot change), and remove it withDELETE /purchase-orders/{id}/tracking/{trackingId}. A number already on an order is codeduplicate_tracking.GET /purchase-orders?tracking=finds the order holding a number.POST /purchase-orders/{id}/receivetakestracking(the number as typed or scanned from the label) ortracking_idto mark that box received with the delivery; a number on another order is codetracking_not_on_order, one you do not have isunknown_tracking. - Correcting an order:
PATCH /purchase-orders/{id}/correctchanges 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 oflinesor 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) plusremove: true; counts are totals, not deltas.fees, when sent, replaces the whole fee list.trackingtakes{add: [...], remove: [ids]}. The order number cannot change, and unknown fields are refused. A refused correction is codeinvalid_correctionwith the app's message; the response carries the updated order andchanged(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.