ShelfCycle Public API v1.20

Endpoint details for resolving records, reading order context and permitted margin details, comparing governed sales and purchasing periods, managing parent-scoped locations and addresses, and maintaining bounded product and product-family records with optional readiness checks and machine-readable repair guidance.

Get Started OpenAPI JSON llms.txt Markdown

OpenAPI summary

ShelfCycle Public API

Routes, scopes, parameters, request bodies, responses, and common error outcomes from the v1.20 contract.

Markdown OpenAPI JSON llms.txt

GET

/api/v1/openapi.json

Get the generated OpenAPI specification

Auth: Public
Scope: Live key and user permissions
Success: 200: Generated OpenAPI 3.1 document. application/json object with openapi, info
Common errors: 405: Method not allowed. application/json object with error; 500: An unexpected server error occurred. application/json object with error

GET

/api/v1/me

Inspect the authenticated API key

Auth: Bearer API key
Scope: Live key and user permissions
Success: 200: Authenticated API key, acting user, documentation, and effective capabilities. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

GET

/api/v1/search

Search public API records

Auth: Bearer API key
Scope: search:read
Parameters: q (query, required, string); types (query, optional, string); limit (query, optional, string)
Success: 200: Search result cards and request metadata. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

GET

/api/v1/reports

List governed reports

Auth: Bearer API key
Scope: reports:read
Success: 200: Report catalog. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

GET

/api/v1/reports/{reportKey}

Run a governed report

Auth: Bearer API key
Scope: reports:read
Parameters: reportKey (path, required, enum: sales-summary, purchase-summary, open-sales-orders); groupBy (query, optional, string); dateField (query, optional, enum: invoiceDate, shipDate, orderDate); startDate (query, optional, string)
Success: 200: Report rows, basis, and pagination metadata. application/json body
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/notes

List notes for a visible subject

Auth: Bearer API key
Scope: notes:read
Parameters: primarySubjectType (query, required, enum: customer, supplier, product); primarySubjectId (query, required, string uuid); limit (query, optional, string)
Success: 200: Subject-scoped note summaries. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

POST

/api/v1/notes

Create a public API note

Auth: Bearer API key
Scope: notes:write
Parameters: dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with primarySubject, noteType, title, body, happenedAt
Success: 200: Idempotent replay returned the existing note, or dryRun returned write readiness. application/json body; 201: Note created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/notes/{id}

Get a public API note

Auth: Bearer API key
Scope: notes:read or notes:write
Parameters: id (path, required, string uuid)
Success: 200: Note detail. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

PATCH

/api/v1/notes/{id}

Update a public API note

Auth: Bearer API key
Scope: notes:write
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); If-Match (header, optional, string)
Body: required application/json object with linkedRecords, noteType, title, body, happenedAt
Success: 200: Updated note detail, or dryRun returned write readiness. application/json body
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/contacts

List contacts under one parent

Auth: Bearer API key
Scope: contacts:read
Parameters: parentType (query, required, enum: customer, supplier); parentId (query, required, string uuid); q (query, optional, string); limit (query, optional, string)
Success: 200: Parent-scoped contact summaries. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

POST

/api/v1/contacts

Create a customer or supplier contact

Auth: Bearer API key
Scope: contacts:create
Parameters: dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with parent, name
Success: 200: Idempotent replay returned the existing contact, or dryRun returned write readiness. application/json body; 201: Contact created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/contacts/{id}

Get a contact

Auth: Bearer API key
Scope: contacts:read or contacts:update or search:read
Parameters: id (path, required, string uuid)
Success: 200: Contact detail. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

PATCH

/api/v1/contacts/{id}

Update a contact

Auth: Bearer API key
Scope: contacts:update
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); If-Match (header, optional, string)
Body: required application/json object with name, title, email, phone, mobilePhone, faxNumber, isEmergency, documentTypes
Success: 200: Updated contact detail, or dryRun returned write readiness. application/json body
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/customers

Find customers

Auth: Bearer API key
Scope: customers:read
Parameters: q (query, optional, string); externalId (query, optional, string); pipelineStatus (query, optional, enum: ACTIVE, PROSPECT); limit (query, optional, string)
Success: 200: Customer finder summaries. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

POST

/api/v1/customers

Create a customer profile

Auth: Bearer API key
Scope: customers:write
Parameters: dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with name
Success: 200: Idempotent replay returned the existing customer profile, or dryRun returned write readiness. application/json body; 201: Customer profile created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/customers/{id}

Get a customer

Auth: Bearer API key
Scope: customers:read or search:read
Parameters: id (path, required, string uuid)
Success: 200: Customer detail. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

PATCH

/api/v1/customers/{id}

Update a customer profile

Auth: Bearer API key
Scope: customers:write
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); If-Match (header, optional, string)
Body: required application/json object with name, externalId, pipelineStatus, primaryLocation
Success: 200: Updated customer profile, or dryRun returned write readiness. application/json body
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/customers/{id}/documents

List customer documents

Auth: Bearer API key
Scope: customers:read or search:read
Parameters: id (path, required, string uuid)
Success: 200: Customer attached documents. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

POST

/api/v1/customers/{id}/documents

Attach a customer document link

Auth: Bearer API key
Scope: customers:write
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with fileName, url
Success: 200: Idempotent replay returned the existing customer document, or dryRun returned write readiness. application/json body; 201: Customer document created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/reference/customers

Page active customer references

Auth: Bearer API key
Scope: company-reference:read
Parameters: limit (query, optional, string); cursor (query, optional, string); includeArchived (query, optional, enum: false)
Success: 200: Active customer reference rows and cursor metadata. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

GET

/api/v1/customers/{id}/locations

List customer locations

Auth: Bearer API key
Scope: customers:read or search:read
Parameters: id (path, required, string uuid); limit (query, optional, string); cursor (query, optional, string)
Success: 200: Parent-scoped active customer locations. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

POST

/api/v1/customers/{id}/locations

Create a customer location

Auth: Bearer API key
Scope: customers:write
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with name, address
Success: 200: Idempotent replay returned the existing customer location, or dryRun returned write readiness. application/json body; 201: Customer location created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/customers/{id}/locations/{locationId}

Get a customer location

Auth: Bearer API key
Scope: customers:read or search:read
Parameters: id (path, required, string uuid); locationId (path, required, string uuid)
Success: 200: Customer location detail. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

PATCH

/api/v1/customers/{id}/locations/{locationId}

Update a customer location

Auth: Bearer API key
Scope: customers:write
Parameters: id (path, required, string uuid); locationId (path, required, string uuid); dryRun (query, optional, enum: true); If-Match (header, optional, string)
Body: required application/json object with name, email, website, phone, primary, makePrimary
Success: 200: Updated customer location, or dryRun returned write readiness. application/json body
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/customers/{id}/locations/{locationId}/addresses

List customer location addresses

Auth: Bearer API key
Scope: customers:read or search:read
Parameters: id (path, required, string uuid); locationId (path, required, string uuid); limit (query, optional, string); cursor (query, optional, string)
Success: 200: Parent-scoped active customer addresses. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

POST

/api/v1/customers/{id}/locations/{locationId}/addresses

Create a customer address

Auth: Bearer API key
Scope: customers:write
Parameters: id (path, required, string uuid); locationId (path, required, string uuid); dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with name
Success: 200: Idempotent replay returned the existing customer address, or dryRun returned write readiness. application/json body; 201: Customer address created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/customers/{id}/locations/{locationId}/addresses/{addressId}

Get a customer address

Auth: Bearer API key
Scope: customers:read or search:read
Parameters: id (path, required, string uuid); locationId (path, required, string uuid); addressId (path, required, string uuid)
Success: 200: Customer address detail. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

PATCH

/api/v1/customers/{id}/locations/{locationId}/addresses/{addressId}

Update a customer address

Auth: Bearer API key
Scope: customers:write
Parameters: id (path, required, string uuid); locationId (path, required, string uuid); addressId (path, required, string uuid); dryRun (query, optional, enum: true)
Body: required application/json object with street1, street2, city, state, zip, country, name, externalId
Success: 200: Updated customer address, or dryRun returned write readiness. application/json body
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/product-families

Find product families

Auth: Bearer API key
Scope: products:read or products:write or search:read
Parameters: q (query, optional, string); externalId (query, optional, string); limit (query, optional, string)
Success: 200: Product family reference summaries. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

POST

/api/v1/product-families

Create a product family

Auth: Bearer API key
Scope: products:write
Parameters: dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with name
Success: 200: Idempotent replay returned the existing product family, or dryRun returned write readiness. application/json body; 201: Product family created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/product-families/{id}

Get a product family reference

Auth: Bearer API key
Scope: products:read or products:write or search:read
Parameters: id (path, required, string uuid)
Success: 200: Product family reference detail. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

PATCH

/api/v1/product-families/{id}

Update a product family

Auth: Bearer API key
Scope: products:write
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); If-Match (header, optional, string)
Body: required application/json object with name, externalId, casNumber, molecularFormula, unNumbers, ghsSignalWord, hazardSymbols
Success: 200: Updated product family, or dryRun returned write readiness. application/json body
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/reference/product-packaging

List product packaging references

Auth: Bearer API key
Scope: products:read or products:write or search:read
Parameters: q (query, optional, string); unitOfMeasure (query, optional, string); limit (query, optional, string)
Success: 200: Product packaging reference summaries. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

GET

/api/v1/products

Find products

Auth: Bearer API key
Scope: products:read
Parameters: q (query, optional, string); code (query, optional, string); externalId (query, optional, string); supplierId (query, optional, string uuid)
Success: 200: Product finder summaries. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

POST

/api/v1/products

Create a product

Auth: Bearer API key
Scope: products:write
Parameters: dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with code, productFamilyId, packagingId, qty
Success: 200: Idempotent replay returned the existing product, or dryRun returned write readiness. application/json body; 201: Product created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/products/{id}

Get a product

Auth: Bearer API key
Scope: products:read or search:read
Parameters: id (path, required, string uuid)
Success: 200: Product detail. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

PATCH

/api/v1/products/{id}

Update a product

Auth: Bearer API key
Scope: products:write
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); If-Match (header, optional, string)
Body: required application/json object with code, externalId, productFamilyId, packagingId, supplierId, packagingType, supplierType, qty
Success: 200: Updated product, or dryRun returned write readiness. application/json body
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/products/{id}/documents

List product documents

Auth: Bearer API key
Scope: products:read or search:read
Parameters: id (path, required, string uuid)
Success: 200: Product attached documents and optional SDS entry. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

POST

/api/v1/products/{id}/documents

Attach a product document link

Auth: Bearer API key
Scope: products:write
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with fileName, url
Success: 200: Idempotent replay returned the existing product document, or dryRun returned write readiness. application/json body; 201: Product document created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/suppliers

Find suppliers

Auth: Bearer API key
Scope: suppliers:read
Parameters: q (query, optional, string); externalId (query, optional, string); limit (query, optional, string); includeArchived (query, optional, string)
Success: 200: Supplier finder summaries. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

POST

/api/v1/suppliers

Create a supplier profile

Auth: Bearer API key
Scope: suppliers:write
Parameters: dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with name
Success: 200: Idempotent replay returned the existing supplier profile, or dryRun returned write readiness. application/json body; 201: Supplier profile created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/suppliers/{id}

Get a supplier

Auth: Bearer API key
Scope: suppliers:read or search:read
Parameters: id (path, required, string uuid)
Success: 200: Supplier detail. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

PATCH

/api/v1/suppliers/{id}

Update a supplier profile

Auth: Bearer API key
Scope: suppliers:write
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); If-Match (header, optional, string)
Body: required application/json object with name, externalId, phone, email, website, street1, street2, city
Success: 200: Updated supplier profile, or dryRun returned write readiness. application/json body
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/suppliers/{id}/documents

List supplier documents

Auth: Bearer API key
Scope: suppliers:read or search:read
Parameters: id (path, required, string uuid)
Success: 200: Supplier attached documents. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

POST

/api/v1/suppliers/{id}/documents

Attach a supplier document link

Auth: Bearer API key
Scope: suppliers:write
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with fileName, url
Success: 200: Idempotent replay returned the existing supplier document, or dryRun returned write readiness. application/json body; 201: Supplier document created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/reference/suppliers

Page active supplier references

Auth: Bearer API key
Scope: company-reference:read
Parameters: limit (query, optional, string); cursor (query, optional, string); includeArchived (query, optional, enum: false)
Success: 200: Active supplier reference rows and cursor metadata. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

GET

/api/v1/suppliers/{id}/ship-from-locations

List supplier ship-from locations

Auth: Bearer API key
Scope: suppliers:read or search:read
Parameters: id (path, required, string uuid); limit (query, optional, string); cursor (query, optional, string)
Success: 200: Parent-scoped active supplier ship-from locations. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

POST

/api/v1/suppliers/{id}/ship-from-locations

Create a supplier ship-from location

Auth: Bearer API key
Scope: suppliers:write
Parameters: id (path, required, string uuid); dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json object with name
Success: 200: Idempotent replay returned the existing supplier ship-from location, or dryRun returned write readiness. application/json body; 201: Supplier ship-from location created. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/suppliers/{id}/ship-from-locations/{locationId}

Get a supplier ship-from location

Auth: Bearer API key
Scope: suppliers:read or search:read
Parameters: id (path, required, string uuid); locationId (path, required, string uuid)
Success: 200: Supplier ship-from location detail. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

PATCH

/api/v1/suppliers/{id}/ship-from-locations/{locationId}

Update a supplier ship-from location

Auth: Bearer API key
Scope: suppliers:write
Parameters: id (path, required, string uuid); locationId (path, required, string uuid); dryRun (query, optional, enum: true); If-Match (header, optional, string)
Body: required application/json object with street1, street2, city, state, zip, country, name, externalId
Success: 200: Updated supplier ship-from location, or dryRun returned write readiness. application/json body
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/orders

Find sales orders

Auth: Bearer API key
Scope: orders:read
Parameters: orderNo (query, optional, string); customerOrderNo (query, optional, string); externalId (query, optional, string); customerId (query, optional, string uuid)
Success: 200: Sales-order finder summaries. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

GET

/api/v1/orders/{id}

Get a sales-order commercial document

Auth: Bearer API key
Scope: orders:read
Parameters: id (path, required, string uuid)
Success: 200: Sales-order commercial document. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/purchase-orders

Find purchase orders

Auth: Bearer API key
Scope: purchase-orders:read
Parameters: orderNo (query, optional, string); externalId (query, optional, string); supplierId (query, optional, string uuid); linkedOrderId (query, optional, string uuid)
Success: 200: Purchase-order finder summaries. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 405: Method not allowed. application/json object with error; 422: Request validation failed. Validation responses include param and errors[]. application/json object with error

GET

/api/v1/purchase-orders/{id}

Get a purchase-order commercial document

Auth: Bearer API key
Scope: purchase-orders:read
Parameters: id (path, required, string uuid)
Success: 200: Purchase-order commercial document. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

GET

/api/v1/cost-book-entries

Read current or historical Cost Book entries

Auth: Bearer API key
Scope: cost-book-entries:read
Parameters: view (query, optional, string); asOf (query, optional, string); productId (query, optional, string); supplierId (query, optional, string)
Success: 200: Current or historical Cost Book entries and signed cursor metadata. application/json object with data, meta
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API key is missing a required scope or the acting user lacks live RBAC permission. application/json object with error; 404: The requested record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

POST

/api/v1/cost-book-entries

Create or supersede verified Cost Book truth

Auth: Bearer API key
Scope: cost-book-entries:write
Parameters: dryRun (query, optional, enum: true); Idempotency-Key (header, optional, string)
Body: required application/json body
Success: 200: Idempotent replay receipt, or dryRun returned write readiness. application/json body; 201: Created or superseded Cost Book entry receipt. application/json object with data
Common errors: 401: Bearer API key is missing, invalid, expired, revoked, or issued to an inactive actor. application/json object with error; 403: The API actor lacks Cost Book write access. application/json object with error; 404: The requested parent or record was not found in the authenticated org. application/json object with error; 405: Method not allowed. application/json object with error

Route v1 / Contract v1.20Bearer API keyIdempotent writesRepair-aware errorsOptional write readinessGoverned reportsParent-scoped child writesProduct catalog writes

Loading API reference...