Commercial documents
Read sales and purchase order context, including permitted cost, profit, and margin details, without mutating orders, receiving, accounting, or cost internals.
v1.11 added scope-gated profit, margin, and cost details for scoped workflows. In the API contract, those fields are grouped under commercialEconomics and require the commercial-economics:read scope alongside the relevant order read scope.
Commercial documents are sales-order and purchase-order records. They are separate from attached customer, supplier, and product document links.
Endpoints
| Endpoint | Scope | Returns |
|---|---|---|
GET /orders | orders:read | Narrowed sales-order finder summaries. Finder responses do not include profit, margin, or cost-basis details. |
GET /orders/{id} | orders:read | Read-only sales-order header, line items, stored totals, and scoped profit, margin, and cost details when permitted. |
GET /purchase-orders | purchase-orders:read | Narrowed purchase-order finder summaries. Finder responses do not include detailed cost participation metadata. |
GET /purchase-orders/{id} | purchase-orders:read | Read-only purchase-order header, line items, stored totals, base and landed line amounts, and scoped cost rows when permitted. |
Use the finder first unless you already have a selected id from search or a previous public response.
Access model
Order document access is intentionally split:
| Scope | What it unlocks |
|---|---|
orders:read | Sales-order finder and exact sales-order document reads. |
purchase-orders:read | Purchase-order finder and exact purchase-order document reads. |
commercial-economics:read | Profit, margin, cost basis, cost rows, and totals explanations where the source data supports them. |
commercial-economics:read does not grant document access by itself. It only applies with the relevant order read scope and the acting user's current ShelfCycle permissions.
Sales orders
curl "$SHELFCYCLE_API_BASE_URL/orders?orderNo=SO-10042" \
-H "Authorization: Bearer $SHELFCYCLE_API_KEY"
Sales-order documents include customer context, shipping instructions, line items, and stored totals. With the profit and margin scope (commercial-economics:read), they can also include:
| Field | Use it for |
|---|---|
commercialEconomics | Revenue, cost, profit, margin, cost-basis summary, and totals explanation. |
lineItems[].costBasis | Known or unavailable product-line cost basis, including source and match confidence. |
lineItems[].economicsParticipation | Whether a line participates as marginable revenue or non-margin revenue. |
costs[].economicsParticipation | Whether a visible cost participates as sales-order cost, purchase-order cost, or non-margin cost. |
If cost basis is incomplete, commercialEconomics.economicsStatus reports incomplete_cost_basis. In that case, total cost, profit, and margin are null rather than guessed.
Purchase orders
curl "$SHELFCYCLE_API_BASE_URL/purchase-orders?orderNo=PO-4812" \
-H "Authorization: Bearer $SHELFCYCLE_API_KEY"
Purchase-order documents include supplier context, linked sales-order context when present, line items, stored totals, and safe cost rows. With the profit and margin scope (commercial-economics:read), line items include base and landed amounts:
baseUnitCostCents
baseExtendedAmountCents
landedUnitCostCents
landedExtendedAmountCents
Purchase-order costs also include participation metadata:
| Field | Use it for |
|---|---|
totalsExplanation | How item and cost amounts relate to stored document totals. |
documentTotalsParticipation | Whether a line or cost participates in item totals, cost totals, neither, or an unknown basis. |
economicsParticipation | Whether a cost is already represented in item cost basis, contributes as purchase-order cost, or is excluded from margin. |
counterpartyRelationship | Whether the public cost counterparty is the PO supplier, another supplier, or unspecified. |
Cost descriptions for other-supplier or unspecified counterparties are neutralized. Do not infer hidden suppliers, AP records, bills, invoices, GL entries, or private cost history from public PO costs.
Money and quantities
Money fields are string cents. Quantities are decimal strings. Do not convert cents to floating dollar amounts for comparisons.
Line-item interpretation should use these fields together:
packagingType
productQty
quantity
unitPriceCents or unitCostCents
extendedAmountCents
extendedAmountCents is the authoritative line total. Fixed and variable packaging use the same response shape, so callers must not infer totals from quantity alone.
Summing fields safely
Read participation metadata before summing money fields. A visible line or cost may be marginable, non-margin, already represented in item cost basis, excluded from totals, or unknown. If a field is null or an explanation reports an incomplete basis, stop and show the uncertainty instead of filling in a zero.
The public API does not create, patch, receive, bill, invoice, allocate, ship, or post order documents. Treat order endpoints as read-only workflow context.