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 for receiving workflows and the Attached documents guide for uploads and association.

Find sales orders

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:

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

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:

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

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

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:

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.