# Commercial documents

Read order headers, lines, totals, costs, and permitted margin details.

Canonical HTML: https://developer.shelfcycle.com/guides/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

```bash
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

```bash
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:

```text
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:

```text
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.

> **Guardrail**: The public API does not create, patch, receive, bill, invoice, allocate, ship, or post order documents. Treat order endpoints as read-only workflow context.