Inventory over HTTPS for your own software. Authenticate with a company service account (created by the Account Holder under Company → API access): exchange its client id and secret at POST /api/v1/token for a one-hour bearer token, then send Authorization: Bearer <access_token> on every request.

Scopes: inventory:read (reads) and inventory:write (writes; also needs an active subscription). Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 carries Retry-After. Errors are RFC 9457 application/problem+json with a stable code. Money is integer cents in the company's currency; times are ISO 8601 UTC.

Server: https://tlaa-us.com

Sites

Where stock is kept; every item belongs to one site.

GET /api/v1/sites

List sites Every active site of the company, default first. A service account sees every site.

Responses

  • 200 The sites.
    FieldTypeNotes
    data array of Site
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

Items

Inventory items.

GET /api/v1/items

List items Keyset-paginated: follow links.next / links.prev; after and before are opaque cursors.

Parameters

NameInTypeNotes
qquerystringMatches name, SKU or UPC.
sitequeryintegerOnly items at this site (an id from GET /api/v1/sites). Default: every site.
low_stockquerybooleanOnly items at or below their reorder point.
archivedquerybooleanInclude archived items.
sortquerystring (name | sku | quantity | updated) default name
orderquerystring (asc | desc) default asc
per_pagequeryinteger (25 | 50 | 100) default 25
afterquerystringCursor from links.next.
beforequerystringCursor from links.prev.

Responses

  • 200 A page of items.
    FieldTypeNotes
    data array of Item
    links object
    FieldTypeNotes
    self string
    next string | null
    prev string | null
    meta object
    FieldTypeNotes
    per_page integer
    total integer
    sort string
    order string
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/items

Create an item Needs inventory:write and an active subscription. A Sobocoo code is assigned. initial_quantity records an opening count in the ledger. site_id picks the site (default: the company's default site); an item never changes site.

Request body application/json

FieldTypeNotes
initial_quantity integer Opening quantity on hand.
site_id integer The site to stock it at (GET /api/v1/sites). Default: the default site.

Responses

  • 201 Created; Location points at it.
    FieldTypeNotes
    data Item
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

GET /api/v1/items/lookup

Find an item by scanned code Accepts what a scanner reads: a Sobocoo QR URL or 12-character code, a UPC-A / EAN-13 / EAN-8 / GTIN-14, or a SKU.

Parameters

NameInTypeNotes
code requiredquerystring
sitequeryintegerLook only at this site. Default: every site (a SKU or UPC stocked at several sites matches the first).

Responses

  • 200 The item and how the code was read.
    FieldTypeNotes
    data Item
    scan object
    FieldTypeNotes
    kind string (sobocoo | upc_a | ean_13 | ean_8 | gtin_14 | raw)
    code string
    checksum_ok boolean | null
  • 404 Nothing matches (code unknown_code). → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

GET /api/v1/items/{id}

Get an item

Parameters

NameInTypeNotes
id requiredpathinteger

Responses

  • 200 The item.
    FieldTypeNotes
    data Item
  • 404 No such record in this company. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

PATCH /api/v1/items/{id}

Update an item Partial: only the fields sent change. Quantity is the ledger's: use movements or a count.

Parameters

NameInTypeNotes
id requiredpathinteger

Request body application/json

ItemWrite

Responses

  • 200 The updated item.
    FieldTypeNotes
    data Item
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/items/{id}/archive

Archive an item Hidden from lists and refuses movements until restored; nothing is deleted.

Parameters

NameInTypeNotes
id requiredpathinteger

Responses

  • 200 The item.
    FieldTypeNotes
    data Item
  • 404 No such record in this company. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/items/{id}/unarchive

Restore an archived item

Parameters

NameInTypeNotes
id requiredpathinteger

Responses

  • 200 The item.
    FieldTypeNotes
    data Item
  • 404 No such record in this company. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

Stock

Movements and counts: the ledger.

GET /api/v1/items/{id}/movements

An item's ledger Movements newest first within a range (default the last 90 days).

Parameters

NameInTypeNotes
id requiredpathinteger
fromquerystringStart of the range (ISO 8601, UTC; inclusive). Default 90 days ago.
toquerystringEnd of the range (exclusive). Default tomorrow.
limitqueryintegerRows per page, 1-100. default 50
offsetqueryintegerRows to skip. default 0

Responses

  • 200 Movements.
    FieldTypeNotes
    data array of Movement
    meta object
    FieldTypeNotes
    total integer
    limit integer
    offset integer
    from string
    to string
    quantity_on_hand integer
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/items/{id}/movements

Record a movement Receive, issue, sell or adjust. A receive with comp: true is free units (samples, promos, donations): unit cost 0, comp_value_cents per unit (default the item's unit cost), item cost unchanged. Refusals are 422 with a code: insufficient_stock (below zero without allow_negative), invalid_movement (a sale on an item not for resale, a zero adjust...), item_archived.

Parameters

NameInTypeNotes
id requiredpathinteger

Request body application/json

MovementWrite

Responses

  • 201 Recorded.
    FieldTypeNotes
    data Movement
    quantity_on_hand integer
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

GET /api/v1/movements

Company-wide movement feed Every movement in the company within a range, newest first; optionally one type.

Parameters

NameInTypeNotes
typequerystring (receive | issue | sale | adjust)
sitequeryintegerOnly this site (an id from GET /api/v1/sites). Default: every site.
fromquerystringStart of the range (ISO 8601, UTC; inclusive). Default 90 days ago.
toquerystringEnd of the range (exclusive). Default tomorrow.
limitqueryintegerRows per page, 1-100. default 50
offsetqueryintegerRows to skip. default 0

Responses

  • 200 Movements.
    FieldTypeNotes
    data array of Movement
    meta object
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/items/{id}/count

Set a counted quantity A physical count: the ledger gets one adjust for the difference (201), or nothing when the count already matches (200, changed=false).

Parameters

NameInTypeNotes
id requiredpathinteger

Request body application/json

FieldTypeNotes
count required integer
note string

Responses

  • 201 Adjusted.
    FieldTypeNotes
    data Movement
    quantity_on_hand integer
    changed boolean
  • 200 Already at that count.
    FieldTypeNotes
    data null
    quantity_on_hand integer
    changed boolean
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

Order list

The "to buy" list.

GET /api/v1/order-list

The order list

Parameters

NameInTypeNotes
statusquerystring (active | closed)active = open or ordered; closed = the last 100 received/dismissed. default active
sitequeryintegerOnly this site (an id from GET /api/v1/sites). Default: every site.

Responses

  • 200 Entries.
    FieldTypeNotes
    data array of OrderListEntry
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/order-list

Add an item to the order list Merged into the item's open entry when there is one. Omit quantity for the suggested one (back above the reorder point).

Request body application/json

FieldTypeNotes
item_id required integer
quantity integer

Responses

  • 201 The entry.
    FieldTypeNotes
    data OrderListEntry
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

GET /api/v1/order-list/{id}

Get an entry

Parameters

NameInTypeNotes
id requiredpathinteger

Responses

  • 200 The entry.
    FieldTypeNotes
    data OrderListEntry
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

PATCH /api/v1/order-list/{id}

Change the quantity

Parameters

NameInTypeNotes
id requiredpathinteger

Request body application/json

FieldTypeNotes
quantity required integer

Responses

  • 200 The entry.
    FieldTypeNotes
    data OrderListEntry
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/order-list/{id}/ordered

Mark ordered

Parameters

NameInTypeNotes
id requiredpathinteger

Request body application/json, optional

FieldTypeNotes
reference string Supplier reference / invoice number.

Responses

  • 200 The entry.
    FieldTypeNotes
    data OrderListEntry
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/order-list/{id}/received

Mark received Records the receive movement (unit cost defaults to the item's; quantity to what was ordered) and closes the entry.

Parameters

NameInTypeNotes
id requiredpathinteger

Request body application/json, optional

FieldTypeNotes
unit_cost_cents integer
quantity integer

Responses

  • 201 The entry and the movement.
    FieldTypeNotes
    data OrderListEntry
    movement Movement
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/order-list/{id}/dismiss

Dismiss an entry

Parameters

NameInTypeNotes
id requiredpathinteger

Responses

  • 200 The entry.
    FieldTypeNotes
    data OrderListEntry
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

Purchase orders

Orders placed with suppliers and their receipts.

GET /api/v1/purchase-orders

List purchase orders Newest first, 25 per page, without lines (with tracking numbers).

Parameters

NameInTypeNotes
statusquerystring (all | open | received) default all
trackingquerystringOnly the order holding this tracking number (spaces, dashes and case are ignored).
pagequeryinteger default 1
sitequeryintegerOnly this site (an id from GET /api/v1/sites). Default: every site.

Responses

  • 200 A page of orders.
    FieldTypeNotes
    data array of PurchaseOrder
    meta object
    FieldTypeNotes
    page integer
    pages integer
    per_page integer
    total integer
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/purchase-orders

Create a purchase order Lines may point at open order-list entries, which become "ordered". Every line must be an item of the same site; the order stocks that site. The number must be unique in the company (code duplicate_number). Give the supplier as vendor_id (from GET /api/v1/vendors) or as a supplier name: a name matches a vendor case-insensitively, or is added as a new vendor. vendor_id wins when both are sent. Archived vendors are refused (code invalid_order). Optional tracking numbers go on the order with it; one already on an order of the company is refused (code duplicate_tracking).

Request body application/json

FieldTypeNotes
number required string e.g. PO-1042
vendor_id integer
supplier string A vendor name, matched or added.
notes string
ordered_at string date-time
lines required array of object
fees array of object
tracking array of PurchaseOrderTrackingWrite

Responses

  • 201 Created.
    FieldTypeNotes
    data PurchaseOrder
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

GET /api/v1/purchase-orders/{id}

Get a purchase order

Parameters

NameInTypeNotes
id requiredpathinteger

Responses

  • 200 The order with lines and fees.
    FieldTypeNotes
    data PurchaseOrder
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

PATCH /api/v1/purchase-orders/{id}

Edit supplier or notes Change the vendor with vendor_id, or with a supplier name (matched case-insensitively or added as a new vendor); null for either clears it. Fields left out are unchanged.

Parameters

NameInTypeNotes
id requiredpathinteger

Request body application/json

FieldTypeNotes
vendor_id integer | null
supplier string | null
notes string | null

Responses

  • 200 The order.
    FieldTypeNotes
    data PurchaseOrder
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/purchase-orders/{id}/receive

Record a delivery Good units go into stock at the actual unit cost (which becomes the item's unit cost); damaged and returned units are counted, never stocked. comp_received free units go into stock as a $0 receive carrying their value (the item's unit cost does not change); comp_damaged are counted only. More than outstanding (paid or comp) is refused unless allow_over (code invalid_receipt). Name the box the delivery came in with tracking (a number as typed or scanned, label barcodes included) or tracking_id (a row of this order's tracking array), not both: that number is marked received (its received_at) with the delivery. A number on another order of the company is refused (code tracking_not_on_order, the detail names the order); one the company does not have is code unknown_tracking.

Parameters

NameInTypeNotes
id requiredpathinteger

Request body application/json

FieldTypeNotes
lines required array of object
note string
allow_over boolean default
tracking string The tracking number the delivery came under, as typed or scanned (spaces, dashes and case ignored; a carrier label barcode payload is unpacked). e.g. 1Z 999 AA1 0123 4567 84
tracking_id integer Or the id of one of this order's tracking rows.

Responses

  • 200 The order after the delivery.
    FieldTypeNotes
    data PurchaseOrder
    stocked integer Units put into stock by this call.
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/purchase-orders/{id}/close

Close an order Writes off whatever is still outstanding (code not_receivable when already closed).

Parameters

NameInTypeNotes
id requiredpathinteger

Responses

  • 200 The closed order.
    FieldTypeNotes
    data PurchaseOrder
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

PATCH /api/v1/purchase-orders/{id}/correct

Correct an order Fix an order after the fact, at any status (open, partial, received or closed): what the web app's Edit order form changes, with the same rules and results. Every field is optional; a field left out keeps its stored value, and so does a line left out of lines or a line field left out of its object. fees, when sent, is the full new fee list ([] removes every fee). Line fields use the names of the line resource, so a line read from GET can be edited and sent back. Unknown fields are refused (the order number cannot change). A change in quantity_received moves stock by the difference, referenced "PO <number>": more is a receive at the price paid, fewer an adjustment (it may take stock below zero); quantity_comp_received does the same with $0 comp receives. A changed price paid (above $0) becomes the item's unit cost. A changed received_at re-dates the delivery that completed the order. Unless the order is closed, its status follows the lines. remove: true takes a line off the order once its counts (free units too) are 0, and puts its order-list entry back on the list; the last line cannot be removed (close the order instead). One purchase_order.edited audit entry lists every change; each tracking number added or removed is audited on its own. Refusals are 422 with code invalid_correction (or duplicate_tracking / invalid_tracking for tracking.add) and the same message as the web form.

Parameters

NameInTypeNotes
id requiredpathinteger

Request body application/json

FieldTypeNotes
vendor_id integer | null A vendor from GET /api/v1/vendors; wins over supplier. null (with no supplier) clears the supplier.
supplier string | null A vendor name, matched case-insensitively or added as a new vendor.
notes string | null
ordered_at string date-time
received_at string | null date-time When the order was received; not in the future. Kept to the minute you send (the web form uses quarter hours).
lines array of object
fees array of object The full new fee list.
tracking object
FieldTypeNotes
add array of PurchaseOrderTrackingWrite
remove array of integer Ids of this order's tracking rows.

Responses

  • 200 The order after the correction.
    FieldTypeNotes
    data PurchaseOrder
    changed boolean false when the request changed nothing.
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/purchase-orders/{id}/tracking

Add a tracking number The number is normalized (uppercase, spaces and dashes removed) and its carrier detected from the format (UPS 1Z..., FedEx, USPS, DHL) unless carrier is given. A number already on an order of the company is refused (code duplicate_tracking, the detail names the order); an unreadable one is code invalid_tracking. At most 50 per order.

Parameters

NameInTypeNotes
id requiredpathinteger

Request body application/json

PurchaseOrderTrackingWrite

Responses

  • 201 Added. data is the order with its tracking; tracking is the new row.
    FieldTypeNotes
    data PurchaseOrder
    tracking PurchaseOrderTracking
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

DELETE /api/v1/purchase-orders/{id}/tracking/{trackingId}

Remove a tracking number

Parameters

NameInTypeNotes
id requiredpathinteger
trackingId requiredpathintegerThe id of a tracking row of this order.

Responses

  • 200 Removed; the order without it.
    FieldTypeNotes
    data PurchaseOrder
  • 404 No such record in this company. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

PATCH /api/v1/purchase-orders/{id}/tracking/{trackingId}

Edit a tracking number Change the carrier or the note; the number itself never changes (remove it and add the right one). carrier null detects the carrier from the number again; note null or empty clears it. Fields left out are unchanged. A real change is in the audit trail with before and after.

Parameters

NameInTypeNotes
id requiredpathinteger
trackingId requiredpathintegerThe id of a tracking row of this order.

Request body application/json

FieldTypeNotes
carrier string | null (ups | fedex | usps | dhl | other) null: detect it from the number.
note string | null

Responses

  • 200 data is the order with its tracking; tracking is the edited row.
    FieldTypeNotes
    data PurchaseOrder
    tracking PurchaseOrderTracking
  • 404 No such record in this company. → Problem
  • 422 Invalid fields; errors maps field to message, code says why. → Problem
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

Vendors

Vendors

GET /api/v1/vendors

List vendors The company's vendors by name. Archived vendors only with include_archived=true.

Parameters

NameInTypeNotes
qquerystringOnly vendors whose name, contact, email or account number contains this.
include_archivedqueryboolean default

Responses

  • 200 The vendors.
    FieldTypeNotes
    data array of Vendor
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 403 The token lacks the scope, or writes need an active subscription. → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

Auth

Token exchange and identity.

GET /api/v1/me

Who am I The service account behind the token, its effective scopes and its company. A cheap connectivity check.

Responses

  • 200 The service account.
    FieldTypeNotes
    client_id string
    name string
    scopes array of string
    company object
    FieldTypeNotes
    id integer
    name string
    currency string
    timezone string
  • 401 Missing, expired or revoked bearer token (WWW-Authenticate: Bearer). → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

POST /api/v1/token

Exchange a service account's credentials for a bearer token OAuth 2.0 client_credentials. Send the fields as JSON, as a form body, or the client id and secret as HTTP Basic. Tokens last one hour; get a new one when one expires. Failed exchanges are throttled per IP and per client id.

No token needed.

Request body application/json

FieldTypeNotes
grant_type string (client_credentials) default client_credentials
client_id required string e.g. sbc_4Kq9...
client_secret required string

Responses

  • 200 The token. → TokenResponse
  • 400 Bad grant_type, missing credentials or malformed JSON. → Problem
  • 401 Unknown client, wrong secret, revoked account or suspended company (code invalid_client). → Problem
  • 429 Over the service account's or the company's hourly budget. Retry after Retry-After seconds. → Problem

Schemas

Problem Problem (RFC 9457)

FieldTypeNotes
type required string The shared OpenAPI components of the public API (sobocoo-ojl.9): schemas, reusable responses, headers and parameters that the controllers reference by name. ComponentsDescriber feeds them to the generator, so the document at /api/docs.json follows this file and the controller attributes. e.g. about:blank
title required string e.g. Unprocessable Content
status required integer e.g. 422
detail string e.g. The request has invalid fields.
code string Stable machine-readable code (validation_failed, insufficient_stock, rate_limited, invalid_token, forbidden, not_found, ...). e.g. validation_failed
errors object On a 422: field name => message. e.g. {"name":"Required."}

TokenResponse

FieldTypeNotes
access_token required string The bearer JWT.
token_type required string e.g. Bearer
expires_in required integer e.g. 3600
scope required string e.g. inventory:read inventory:write

SiteRef

The site an item (or order) belongs to.

FieldTypeNotes
id integer e.g. 3
name string e.g. Main

Site

FieldTypeNotes
id required integer e.g. 3
name required string e.g. Main
default required boolean Where items created without a site_id go.
for_resale required boolean Items here carry a list price and can be sold.

VendorRef

The vendor an order is placed with.

FieldTypeNotes
id integer e.g. 7
name string e.g. Staples

Vendor

FieldTypeNotes
id required integer e.g. 7
name required string Unique in the company, case-insensitively. e.g. Staples
contact_name string | null
email string | null
phone string | null
website string | null
account_number string | null The company's account number with the vendor.
notes string | null
archived required boolean Archived vendors stay on their orders; new orders cannot use them.
created_at string date-time
updated_at string date-time

Item

FieldTypeNotes
id required integer e.g. 42
site SiteRef
sku string | null e.g. PEN-1
name required string e.g. Blue pen
upc string | null e.g. 036000291452
sobocoo_code string Platform-unique 12-character code printed in the QR label. e.g. ABCDEFGHJKLM
description string | null
unit string e.g. each
unit_cost_cents integer e.g. 120
price_cents integer 0 when the item does not track a price. e.g. 250
currency string e.g. USD
for_resale boolean
tracks_price boolean Site for resale AND item for resale: Sell is possible.
quantity_on_hand required integer e.g. 12
reorder_point integer e.g. 5
low_stock boolean
location string | null
archived boolean
created_at string date-time
updated_at string date-time
links object
FieldTypeNotes
self string uri
movements string uri
qr string uri The URL encoded in the item's QR label.

ItemWrite

Fields of an item. On PATCH every field is optional; unknown fields are a 422.

FieldTypeNotes
name string e.g. Blue pen
sku string | null Unique within the site.
upc string | null UPC-A / EAN-13 / EAN-8 / GTIN-14 with a valid check digit.
description string | null
unit string e.g. each
unit_cost_cents integer
price_cents integer Only when the item tracks a price.
for_resale boolean
reorder_point integer
location string | null

Movement

FieldTypeNotes
id required integer
item_id required integer
type required string (receive | issue | sale | adjust)
quantity required integer Signed: receive adds, issue and sale subtract, adjust carries its own sign. e.g. 10
unit_cost_cents integer | null
comp_value_cents integer | null A comp (free) receive: what each unit was worth; unit_cost_cents is then 0. Null on other movements.
unit_price_cents integer | null
buyer string | null
note string | null
reference string | null e.g. PO 1042
occurred_at required string date-time
recorded_by string | null e.g. API: POS bridge
created_at string date-time

MovementWrite

FieldTypeNotes
type required string (receive | issue | sale | adjust)
quantity required integer receive/issue/sale: the positive unit count; adjust: the signed delta (non-zero). e.g. 5
unit_cost_cents integer receive only; defaults to the item's unit cost.
unit_price_cents integer sale only; defaults to the item's price.
buyer string sale only.
note string
reference string PO / invoice number; searchable in the audit trail.
occurred_at string date-time Defaults to now.
allow_negative boolean Let stock go below zero (the ledger then shows the truth; a count can fix it). default
comp boolean receive only: free (comp) units such as samples, promos or donations. Recorded at unit cost 0 with comp_value_cents; unit_cost_cents is ignored and the item's unit cost does not change. default
comp_value_cents integer With comp: true, what each unit is worth; defaults to the item's unit cost.

OrderListEntry

FieldTypeNotes
id required integer
item_id required integer
item_sku string | null
item_name string
quantity required integer
status required string (open | ordered | received | dismissed)
source string (web | scan | api)
reference string | null
purchase_order_id integer | null
received_movement_id integer | null
created_at string date-time
updated_at string date-time

PurchaseOrderLine

FieldTypeNotes
id integer
item_id integer
item_sku string | null
item_name string
order_list_entry_id integer | null
quantity_ordered integer
expected_unit_cost_cents integer
quantity_received integer
quantity_damaged integer
quantity_returned integer
actual_unit_cost_cents integer | null
return_reason string | null
quantity_comp integer Comp (free) units promised on top of quantity_ordered.
quantity_comp_received integer Comp units received into stock (at $0).
quantity_comp_damaged integer Comp units that arrived damaged (not stocked).
comp_unit_value_cents integer What one comp unit is worth: the paid unit cost, or the item's cost when that is 0.
outstanding integer Paid units still expected.
comp_outstanding integer Comp units still expected.
complete boolean Nothing more expected, paid or comp.

PurchaseOrderTracking

A carrier tracking number on a purchase order. Unique within the company.

FieldTypeNotes
id required integer
number required string Normalized: uppercase, no spaces or dashes. e.g. 1Z999AA10123456784
carrier required string (ups | fedex | usps | dhl | other) Detected from the number unless given when it was added.
carrier_label string e.g. UPS
tracking_url string | null uri The carrier's tracking page; null for other.
note string | null
added_by string | null
created_at string date-time
received_at string | null date-time When a delivery was recorded from this number.

PurchaseOrderTrackingWrite

FieldTypeNotes
number required string As typed or scanned; spaces and dashes are removed and letters uppercased (6-64 letters and digits after that). e.g. 1Z 999 AA1 0123 4567 84
carrier string (ups | fedex | usps | dhl | other) Leave out to detect it from the number.
note string

PurchaseOrder

FieldTypeNotes
id required integer
site SiteRef
number required string e.g. PO-1042
supplier string | null The linked vendor's current name, the same as vendor.name; null when the order has no vendor. Kept for compatibility; prefer vendor.
vendor object The vendor record, with its current name; null when the order has no supplier.
status required string (open | partial | received | closed)
notes string | null
ordered_at string date-time
received_at string | null date-time
closed_at string | null date-time
placed_by string | null
expected_subtotal_cents integer
fees_total_cents integer
expected_total_cents integer
actual_total_cents integer
comp_units integer Comp (free) units promised across the lines; never in the totals.
comp_value_cents integer Value of the comp units promised.
comp_received_value_cents integer Value of the comp units received.
outstanding_units integer Units still expected, paid and comp.
receivable boolean
tracking array of PurchaseOrderTracking Carrier tracking numbers, oldest first.
lines array of PurchaseOrderLine Only on the single-order responses.
fees array of object

Response headers