# Commercial documents

Find and read sales and purchase orders with fulfillment, receipt, line, and totals context.

Canonical HTML: https://developer.shelfcycle.com/guides/commercial-documents

Find and read sales and purchase orders, then follow open purchase lines through receiving with exact event and document context.

Commercial documents are sales-order and purchase-order records. They are separate from files attached to a customer, supplier, product, or purchase order.

## Endpoints

| Endpoint | Scope | Returns |
| --- | --- | --- |
| `GET /orders` | `orders:read` | Sales-order summaries narrowed by exact identifiers, status, customer, product, related purchase order, business date, or last update. |
| `GET /orders/{id}` | `orders:read` | Sales-order header, line items, fulfillment progress, stored totals, and line-page coverage. |
| `GET /purchase-orders` | `purchase-orders:read` | Purchase-order summaries narrowed by exact identifiers, status, supplier, product, related sales order, due date, or last update. |
| `GET /purchase-orders/{id}` | `purchase-orders:read` | Purchase-order header, line items, receipt progress, supplier document costs, stored totals, and line-page coverage. |
| `GET /purchase-order-execution` | `purchase-order-execution:read` | Current open purchase lines with receipt state, comparable quantities, evidence quality, and continuation. |
| `GET /purchase-order-lines/{id}/receipt-events` | `purchase-order-execution:read` | Exact receipt events for one visible purchase-order line. |
| `GET /purchase-orders/{id}/documents` | `purchase-order-execution:read` | Documents attached to one visible purchase order. |
| `POST /purchase-orders/{id}/documents` | `purchase-order-documents:write` | Preview or attach one document to a visible purchase order. |

Use the finder first unless you already have a selected id from search or a previous response.

## Access

| Scope | What it unlocks |
| --- | --- |
| `orders:read` | Sales-order finder and exact sales-order reads. |
| `purchase-orders:read` | Purchase-order finder and exact purchase-order reads. |
| `purchase-order-execution:read` | Current open purchase lines, receipt events, and attached purchase-order documents. |
| `purchase-order-documents:write` | Readiness checks and document association for a visible purchase order. |

The sales- and purchase-order read scopes also follow the acting user's current ShelfCycle order permissions.

The execution and document scopes also follow the acting user's current purchase-order permissions. See the [Purchase execution guide](/guides/purchase-execution) for receiving workflows and the [Attached documents guide](/guides/attached-documents) for uploads and association.

## Find sales orders

```bash
curl "$SHELFCYCLE_API_BASE_URL/orders?customerId=customer-id&fromDate=2026-07-01&toDate=2026-07-31&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

Choose one or more supported filters:

| Filter | Use it for |
| --- | --- |
| `orderNo`, `customerOrderNo`, `externalId` | One exact identifier or up to 25 comma-separated exact identifiers. |
| `customerId` | Orders for one customer. |
| `productId`, `productFamilyId` | Orders containing a selected product or product family. |
| `linkedPurchaseOrderId` | Sales orders related to one purchase order. |
| `status` | Orders in one documented sales-order status. |
| `fromDate` and `toDate` | An inclusive ordered-date range in the organization's time zone. |
| `changedFrom` and `changedTo` | A half-open last-updated range of up to 30 days. |

Finder rows include the customer, status, order dates, related purchase order, document total and currency, product ids, URL, and `updatedAt`.

Batch known customer order references in one exact request:

```bash
curl "$SHELFCYCLE_API_BASE_URL/orders?customerOrderNo=A,B,C&limit=5" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

`orderNo`, `customerOrderNo`, and `externalId` each accept as many as 25 exact comma-separated values.

## Find purchase orders

```bash
curl "$SHELFCYCLE_API_BASE_URL/purchase-orders?supplierId=supplier-id&fromDate=2026-08-01&toDate=2026-08-31&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

Purchase-order finders accept `orderNo`, `externalId`, `supplierId`, `productId`, `productFamilyId`, `linkedSalesOrderId`, `status`, a paired `fromDate` and `toDate` due-date range, or a paired `changedFrom` and `changedTo` last-updated range. `orderNo` and `externalId` each accept as many as 25 exact comma-separated values.

Finder rows include the supplier, status, submitted, confirmed, completed, received, ship, and due dates when present, related sales order, document total and currency, product ids, URL, and `updatedAt`.

## Continue finder results

Set `limit` from 1 to 25. When `meta.hasMore` is true, make the next request with `meta.nextCursor` and no other query parameters:

```bash
curl "$SHELFCYCLE_API_BASE_URL/orders?cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

The signed cursor keeps the original filters, order, and result snapshot together. Finder metadata reports the returned row count, ordering, snapshot time, and the next cursor.

## Read sales-order detail

```bash
curl "$SHELFCYCLE_API_BASE_URL/orders/order-id?lineLimit=100" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

Sales-order detail includes:

| Field | Use it for |
| --- | --- |
| `header` | Order identity, status, customer, related purchase order, ship-to address, shipping instructions, dates, assignee, warehouse, and freight details. |
| `lineItems` | Product or non-product lines with quantity, product quantity, UOM, unit price, extended amount, and currency. |
| `lineItems[].fulfillment` | Whether the line is allocated, uses virtual inventory, and when it was consumed. |
| `totals` | Stored subtotal, tax, shipping, fee, total, and document currency. |
| `lineCoverage` | Total and returned line counts plus the next line cursor. |

## Read purchase-order detail

```bash
curl "$SHELFCYCLE_API_BASE_URL/purchase-orders/purchase-order-id?lineLimit=100" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

Purchase-order detail includes:

| Field | Use it for |
| --- | --- |
| `header` | Order identity, status, supplier, supplier instructions, related sales order, ship-from address, dates, assignee, warehouse, and freight details. |
| `lineItems` | Product lines with quantity, product quantity, UOM, unit cost, extended amount, and currency. |
| `lineItems[].receipt` | Receipt count, first and last receipt dates, and virtual-inventory status. |
| `costs` | Supplier document cost rows with description, amount, currency, and related line when present. |
| `totals` | Stored item amount, non-item cost amount, total, and document currency. |
| `lineCoverage` | Total and returned line counts plus the next line cursor. |

## Continue line items

Order detail returns 100 lines by default. Set `lineLimit` from 1 to 500. When `lineCoverage.hasMore` is true, keep the same order id and pass `lineCoverage.nextLineCursor` by itself:

```bash
curl "$SHELFCYCLE_API_BASE_URL/orders/order-id?lineCursor=$NEXT_LINE_CURSOR" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

## Money and quantities

Money fields are string cents in the reported three-letter currency. Quantities are decimal strings. Read `quantity`, `productQuantity`, `uom`, unit price or cost, and `extendedAmountCents` together. Use the returned totals as the document totals.