Get Started

Changelog

Product updates for the ShelfCycle Developer API.

Public API v1.20

Expanded governed reports with flexible sales and purchasing period comparisons.

New

  • Sales and purchase summaries can compare any two explicit, bounded date windows, including quarter-over-quarter, year-over-year, and custom-period analysis.
  • Comparison rows include primary and comparison measures, signed changes, and new, lost, or retained activity classification.
  • Report totals and ranking metadata describe the complete filtered population before pagination, with sorting by current values, comparison values, or change.

Useful for

  • Teams can rank the largest sales, gross-profit, margin, or purchase-spend changes and identify newly active or no-longer-active customers and suppliers.
  • Agents can answer period-over-period questions in one governed report call while distinguishing a ranked page from a complete result set.

Notes

  • Report access still requires reports:read plus the acting user's live ShelfCycle permissions, and money remains cents-as-string in the org base currency.
  • Sales comparisons use customer, product-family, product-code, salesperson, or supplier groupings. Month rollups remain available for single-period reporting.

Public API v1.19

Added governed report rollups for sales, purchasing, and open order value.

New

  • New reports:read scope with GET /reports for catalog discovery and GET /reports/{reportKey} for read-only report runs.
  • Catalog rows publish available keys, parameters, dimensions, measures, and allowedForThisKey so clients can choose only reports the current key and actor can run.
  • Initial reports cover sales-summary, purchase-summary, and open-sales-orders with paged rows and string-cent money fields in the org base currency.

Useful for

  • Teams can power customer, product-family, product-code, supplier, salesperson, month, purchase-spend, and open-order dashboards from the same governed API surface.
  • Agents can discover report availability before running a rollup and keep unsupported report access out of automated workflows.

Notes

  • Report access requires reports:read plus the acting user's live ShelfCycle permissions.
  • Reports are read-only rollups. Order changes, purchase-order changes, row-level exports, scheduling, files, inventory valuation, cost recalculation, AR/AP/GL, and accounting work still happen in ShelfCycle.

Public API v1.18

Added parent-scoped document links for products, customers, and suppliers.

New

  • Products, customers, and suppliers now support parent-scoped document lists after a caller selects a visible record.
  • Authorized writes can attach one HTTPS file link to an active parent with dry-run readiness, idempotency, duplicate checks, and readback guidance.
  • Product document lists include the product SDS pointer when one is available, alongside attached document rows.

Useful for

  • Customer onboarding can attach W-9s, credit applications, COIs, SDS/TDS files, specs, or similar source files to the exact record already chosen by the workflow.
  • Teams can let agents collect links from intake systems while ShelfCycle keeps file access tenant-bound and parent-scoped.

Notes

  • ShelfCycle-hosted files return short-lived signed read URLs; external HTTPS links return their original URL.
  • Use these routes when a workflow needs to add or review file links for the selected product, customer, or supplier. File uploads, document deletion, sales order or purchase order changes, inventory, pricing, costing, and accounting still happen in ShelfCycle.

Public API v1.17

Expanded product setup into bounded product and product-family maintenance.

New

  • Product records now support PATCH with dry-run readiness, optimistic concurrency, duplicate checks, and impact analysis.
  • Product families now support create and update workflows for public-safe identity, CAS, formula, UN, signal-word, and hazard-symbol fields.
  • GET /me reports product and product-family capabilities separately so integrations can verify create and update access before acting.

Useful for

  • Teams can keep reviewed catalog facts aligned as intake, SDS/TDS review, and supplier context changes.
  • Agents can preview order-sensitive effects before changing product identity, packaging, supplier, or regulatory fields.

Notes

  • Catalog writes stay bounded to safe setup fields and continue to leave packaging, suppliers, inventory, prices, costs, orders, documents, and accounting untouched.

Public API v1.16

Added product setup references and bounded product create with dry-run readiness.

New

  • New products:write scope for bounded product catalog creation from existing product family, packaging, and optional supplier references.
  • New product setup references: GET /product-families, GET /product-families/{id}, and GET /reference/product-packaging.
  • POST /products supports dryRun=true, idempotent execution, duplicate checks, reference eligibility checks, and verification guidance.

Useful for

  • Teams can move intake and onboarding workflows from manual handoffs into controlled catalog creation.
  • Agents can verify product family, packaging, supplier visibility, duplicates, and variable-quantity rules before writing.

Notes

  • Product create is setup-only. It does not update products, create product families or packaging, create suppliers, mutate inventory, pricing, costs, orders, lots, documents, or accounting records.

Public API v1.15

Added parent-scoped customer location, customer address, and supplier ship-from reads and writes.

New

  • Customer location endpoints now support parent-scoped list, detail, create, and update under /customers/{id}/locations.
  • Customer address endpoints now support parent-scoped list, detail, create, and update under /customers/{id}/locations/{locationId}/addresses.
  • Supplier ship-from endpoints now support parent-scoped list, detail, create, and update under /suppliers/{id}/ship-from-locations.

Useful for

  • Onboarding and agent workflows can add ship-to, bill-to, and supplier pickup locations after resolving the exact parent.
  • Dry-run checks can surface duplicates, archived or invisible parents, address-role issues, stale records, and verification availability before mutation.

Notes

  • These endpoints stay scoped to the selected customer or supplier and exclude broad exports, primary switching, archived records, supplier root address changes, and sensitive finance, tax, or ledger fields.

Public API v1.14

Added repair-aware responses that show clients how to correct a request and continue cleanly.

New

  • Validation responses can return structured repair details, including next actions, accepted values, date-window guidance, documentation links, examples, and retry advice.
  • Search, contacts, sales-order, and purchase-order requests now provide more specific guidance when a parameter, filter, or value needs attention.
  • Rate-limit responses now include clearer wait guidance for clients that need to back off cleanly.

Useful for

  • Agents and integrations can use the response itself to choose the next safe request.
  • Teams get fewer stalled workflows when a request needs a small correction.

Notes

  • Repair guidance is additive. Existing scopes, permissions, idempotency, concurrency, and write-readiness checks continue to apply.

Public API v1.13

Added non-mutating readiness checks for supported writes before submitting a change.

New

  • Supported note, contact, customer, and supplier write endpoints now accept dryRun=true for readiness checks.
  • Readiness responses return whether the write is ready, what still needs attention, and the guidance needed to submit or verify the change.
  • GET /me reports write-readiness availability for each permitted write capability.

Useful for

  • Teams can put review gates or automated policies in front of writes without building a separate rules layer.
  • Authorized callers can still execute directly when their own policy allows it.

Notes

  • Execution still rechecks every invariant and keeps the same idempotency and concurrency protections.

Public API v1.12

Added active customer and supplier reference directories for cleaner matching before detail reads and writes.

New

  • New company-reference:read scope for active customer and supplier matching hints.
  • New /reference/customers and /reference/suppliers endpoints with cursor pagination.
  • Reference rows include stable identifiers, display names, common alternate names, website and email matching signals, location summaries, status, and ShelfCycle URLs.

Useful for

  • Integrations can build local matching caches without pulling full company profiles.
  • Callers can match broadly first, then fetch exact records before business decisions or writes.

Notes

  • Reference rows are active-only matching hints, not full customer or supplier profiles.

Public API v1.11

Expanded order document reads with changed-record discovery and scoped commercial economics.

New

  • Sales-order and purchase-order finders now support paired updatedAtFrom/updatedAtTo windows for parent-row changed-record discovery.
  • New commercial-economics:read scope unlocks permitted profit, margin, cost basis, landed-cost, and total explanation fields on scoped order document reads.
  • Sales-order detail can expose commercialEconomics, line-item costBasis, and participation metadata for marginable and non-margin amounts.
  • Purchase-order detail can expose base and landed line amounts, totals explanations, economics participation, and counterparty relationship metadata.

Useful for

  • Order workflows can find recently changed documents without switching into broad exports.
  • Permitted users can see commercial context and totals participation clearly enough to reconcile downstream decisions.

Notes

  • Commercial economics access is scope and permission gated. Read-only order endpoints stay read-only.

Public API v1.1

Expanded the API into a fuller workflow surface for resolving records, reading details, and writing bounded profiles.

New

  • Search now resolves customers, suppliers, contacts, products, sales orders, purchase orders, and locations as typed result cards.
  • Finder endpoints were added for customers, suppliers, products, sales orders, and purchase orders.
  • Detail reads were added for core records, contacts, notes, sales orders, and purchase orders.
  • Customer and supplier profile creates and updates now support idempotency and optimistic concurrency.
  • Subject-scoped notes and parent-scoped contacts keep workflows focused on confirmed records.

Improved

  • Finder and detail responses now publish concrete, resource-specific shapes for generated clients.
  • Money, quantity, and order-line fields use stable formats that clients can treat consistently.

Notes

  • Finders stay filtered and resource-specific, keeping integrations focused on selected workflow context.

Developer API v1

Initial v1 release for resolving ShelfCycle records and writing supported notes or contacts back to confirmed records.

New

  • Bearer API key authentication with GET /me for tenant, scopes, key preview, and acting-user verification.
  • GET /search for typed candidate records with matched fields, parent context, and ShelfCycle URLs.
  • POST /notes and PATCH /notes for supported notes on confirmed customers, suppliers, or products.
  • POST /contacts and PATCH /contacts for supported customer and supplier contacts under existing parents.

Foundations

  • Writes must use stable Idempotency-Key values so retries do not create duplicate notes or contacts.
  • Updates require If-Match so callers can detect stale records before overwriting newer changes.
  • Errors return stable codes, request ids, and retry guidance for programmatic handling.

Notes

  • Supported writes are bounded to confirmed records and policy-approved workflows.