API conventions

Company scoping

Most provider‑facing endpoints take a companyId query parameter and return data for that company only. Your token (or session) must have access to the company, or the request returns 403.

GET /api/catalog/vendor-products?companyId=123
GET /api/inventory/locations?companyId=123

Pagination

List endpoints accept limit and offset and return an envelope with the page plus a total:

{
  "items": [ /* … */ ],
  "total": 248
}

Iterate by advancing offset until you've read total rows. Endpoints cap limit; omit it to take the default page size.

Errors

Errors use standard HTTP status codes with a JSON body:

{
  "statusCode": 403,
  "message": "forbidden: company access denied",
  "error": "Forbidden"
}

Common codes:

Money & dates

• Money is integer cents (listPriceCents, subtotalCents, …) with a separate currency.
• Timestamps are ISO‑8601 UTC strings.
• Large ids are returned as strings to stay precise in JSON.