List the products you can order

GET

/products

curl --request GET \
  --url 'https://api.partners.collaterate.com/v1/products?serviceType=STOCK&limit=100' \
  --header 'Authorization: Bearer <token>'

• Production (OAuth2 client_credentials, bearer token)
• Production (mutual TLS -- see "Authentication" below; only for partners onboarded this way)
• Staging (OAuth2 client_credentials, bearer token)
• Staging (mutual TLS)
• Test-B (OAuth2 client_credentials, bearer token)
• Test-B (mutual TLS)

The orderable catalog across your granted sites, one entry per variant, which is the unit an order line refers to.

This endpoint exists mainly so that ordering is possible at all: an order line must carry a productId and a variantId, and there is no other way to discover either. Neither the sku nor the productCode on an existing order line can be matched back to a catalog entry, so do not try – page this endpoint and key your own catalog on (productId, variantId).

Only orderable products are listed. An entry appears here if and only if it is active, has a fulfillment center assigned, is of a service type this API can order (STOCK or POD), and is visible to everyone on its site. Products a site has hidden, retired or restricted to particular customer segments are not listed, and neither are digital products, which cannot be ordered through this API. An entry absent from this list will be rejected at submission.

Prices are not published here, deliberately. What a product costs depends on variant adjustments, site markup and per-share pricing overrides, so any single column would be a base rate rather than what you pay. Submit the order and the response carries the real per-line and order totals.

Keyset-paginated, ordered by (productId, variantId). Follow nextCursor.

Authorizations

• oauth2
  partner-api/products:read
• mtls

Parameters

Query Parameters

siteId

integer

Restrict the result to a single site. Must be one of the sites listed in your GET /v1/me response. A siteId outside your grant is rejected as a bad request – never silently ignored, and never answered with an empty page.

serviceType

string

Allowed values: STOCK POD

Restrict to one service type. Any other value is rejected rather than answered with an empty page, so that asking for a type this API cannot order is distinguishable from a site that happens to sell none of it.

cursor

string

Opaque pagination token from a previous response’s nextCursor. Do not parse it, construct it, or rely on its format staying the same. Pass it back as received.

limit

integer

default: 100 >= 1 <= 500

Page size. Defaults to 100. Values above 500 are capped at 500, not rejected.

Responses

200

A page of orderable products.

Media typeapplication/json

object

products

required

Array<object>

One orderable variant. (productId, variantId) identifies it, and both are required on the order line that buys it.

object

siteId

required

The granted site this product belongs to.

integer

productId

required

The identifier an order line must carry. Prefixed by origin: SLO_ for a product the site owns, SLS_ for one shared to it. Treat it as an opaque string – the prefix is informative, not something to branch on.

string

variantId

required

The specific variant, or null for a POD product, which has no variant until the job is configured. A STOCK product appears here once per variant.

Send this back exactly as received, null included. An order line whose variantId does not resolve is rejected, and a null is accepted – so do not substitute a placeholder for a POD product.

integer | null

sku

required

null for a POD product, which has no SKU.

string | null

name

required

string

description

required

string | null

serviceType

required

STOCK is warehoused inventory; POD is print-on-demand and is quoted per order. No other type is listed, because no other type can be ordered through this API.

string

Allowed values: STOCK POD

availableInventory

required

Stock on hand, or null when inventoryTracked is false – meaning no quantity can be stated for this product, NOT that it has none. Always null for POD, which is produced per order.

A product is listed whatever this says – zero does not remove it, because a product that vanished at zero would be indistinguishable from one that was discontinued. Whether a shortfall blocks an order is decided when the order is submitted, from the site’s backorder setting.

Before 2026-07-29 an untracked product reported 0 here, which read identically to genuinely out-of-stock; one variant was hiding 2,065 units. If you cached the old value, treat 0 as unknown rather than empty.

integer | null

inventoryTracked

required

Whether availableInventory means anything. When false, this product does not track inventory: no quantity is published, and only submission can tell you whether a given quantity will be accepted.

boolean

minQuantity

required

Minimum orderable quantity, or null for no minimum.

integer | null

maxQuantity

required

Maximum orderable quantity, or null for no maximum.

integer | null

shippable

required

boolean

weight

required

Per-unit weight as a decimal string, or null for a POD product, which has none until the job is configured. A string for the same reason order totals are: the underlying value carries more precision than a JSON number holds.

string | null

updatedOn

required

When the catalog entry last changed. Informational – there is no updatedSince filter on this endpoint, so do not build an incremental sync on it.

string format: date-time

nextCursor

required

Opaque cursor for the next page, or null on the last page. Terminate your loop on null specifically.

string | null

Examples

Exampledefault

{
  "products": [
    {
      "siteId": 42,
      "productId": "SLS_918273",
      "variantId": 55012,
      "sku": "BC-100-WHT",
      "name": "Business Cards",
      "description": "16pt uncoated, full colour both sides",
      "serviceType": "STOCK",
      "availableInventory": 1450,
      "inventoryTracked": true,
      "minQuantity": null,
      "maxQuantity": null,
      "shippable": true,
      "weight": "0.0120000000",
      "updatedOn": "2026-07-14T09:31:00.000Z"
    },
    {
      "siteId": 42,
      "productId": "SLS_1",
      "variantId": null,
      "sku": null,
      "name": "Announcements",
      "description": "Digitally printed, ordered to exact quantity",
      "serviceType": "POD",
      "availableInventory": null,
      "inventoryTracked": false,
      "minQuantity": 50,
      "maxQuantity": 5000,
      "shippable": true,
      "weight": null,
      "updatedOn": "2024-08-01T07:32:35.125Z"
    }
  ],
  "nextCursor": "eyJwIjoiU0xTXzkxODI3MyIsInYiOjU1MDEyfQ"
}

400

A cursor that could not be decoded, a siteId that is not a positive integer or is outside your granted sites, or a serviceType this API cannot order.

Media typeapplication/problem+json

RFC 9457 application/problem+json body. code is the published, stable, machine-readable field to branch your integration logic on – detail is a human-readable string that may be reworded over time and must not be parsed.

This table is the whole published set: every code this API can return appears below, and nothing below is unreachable. test/docs/openapi-matches-reality.test.ts compares the enum to the codes the handlers actually construct, so a code added to one side and not the other fails the build rather than shipping.

Published code values:

code	HTTP status	Meaning	Retry?
invalid_cursor	400	The cursor query parameter could not be decoded.	No – restart pagination with no cursor. Do not resend the same value.
invalid_site_id	400	The siteId filter is not a positive integer, or it names a site outside your grant. detail says which.	No – fix the parameter against GET /v1/me’s grantedSiteIds.
invalid_order_number	400	The order number in the path is not a positive integer.	No – fix the path.
invalid_product_id	400	The productId path segment on GET /v1/products/{productId} does not match the SLO_/SLS_-prefixed shape.	No – fix the path.
invalid_service_type	400	GET /v1/products’s serviceType filter is not one of the values this API can order (STOCK or POD).	No – fix the parameter.
updated_since_not_supported	400	An updatedSince parameter was sent. Rejected rather than ignored, on purpose – see “No updatedSince / no change polling” above.	No – remove the parameter; there is no change-polling mechanism to switch to.
invalid_request	400	POST /v1/orders’s request body failed validation – malformed JSON, a missing or malformed field, an unknown key, or a body-level rule such as partnerLineId uniqueness or a misplaced shipTo – or GET /v1/orders/submissions’s status/limit filter is malformed. detail names the exact violation.	No – fix the request.
invalid_submission_id	400	The submissionId path segment on GET /v1/orders/submissions/{submissionId} is not a well-formed UUID.	No – fix the path.
invalid_quantity	400	The quantity on POST /v1/products/{productId}/quote is missing or not a positive integer.	No – fix the request body.
invalid_token	401	The credential is missing, expired, or invalid.	No – mint a new token, retry once, then investigate the credential.
insufficient_scope	403	The token lacks the scope required for this operation.	No – mint a token with the required scope.
order_not_found	404	No such order, or one that exists outside your granted sites (see above).	No.
product_not_found	404	No such product, or one that exists but belongs to a site outside your granted sites (same rule as order_not_found).	No.
quote_product_not_found	404	The product resolved in our own catalog but Collaterate could not price it. Rare.	No.
submission_not_found	404	No submission exists with this id for your credential – whether it never existed or belongs to another partner, identically.	No.
ordering_not_provisioned	409	POST /v1/orders’s siteId has no ordering user configured. This is set up per (partner, site) by staff at onboarding; a partner cannot provision it themselves.	No – ask Partner Integrations to provision an ordering user for the site, then retry.
partner_order_id_reused	409	POST /v1/orders’s partnerOrderId was already used, with a request body that does not match this one. Resending the identical body under the same partnerOrderId is safe and returns the original submission (see the operation description); reusing it for a materially different order is rejected instead of silently creating a second order.	No – use a new partnerOrderId, or resend the exact original body to poll the existing submission.
quote_invalid	422	Collaterate rejected the quote on business-validation grounds (e.g. quantity over the product’s configured maximum). detail carries Collaterate’s own validation message.	No – fix the request body (e.g. reduce quantity).
rate_limit_exceeded	429	Rate limit or daily quota exceeded.	Yes – honor Retry-After.
internal_error	500	Unexpected server-side failure. Detail is always the fixed string below, never the underlying error.	No, or with caution – if persistent, contact Partner Integrations.
service_unavailable	503	Transient failure – typically the database path, but also a Lambda that crashed, timed out, or hit its own concurrency limit before any handler ran.	Yes, with backoff.

Three statuses are answered by the API gateway before your request reaches application code: 401 (authorizer denial), 429 (usage-plan throttle), and 503 (the Lambda integration itself failed). All three are configured to return this same document with the codes above, so one parser and one branch on code covers every error this API produces. The 403 on GET /v1/ping is the sole exception anywhere in the API – it comes from the edge firewall, which is not ours to shape, and carries no problem document.

object

type

required

Always the literal string about:blank today; reserved by RFC 9457 for future use.

string

Allowed value: about:blank

title

required

Short, human-readable summary of the HTTP status (e.g. “Not Found”).

string

status

required

The HTTP status code, repeated in the body for convenience.

integer

code

required

Stable, machine-readable error identifier. Safe to branch on. See the table above.

string

Allowed values: invalid_cursor invalid_site_id invalid_order_number invalid_product_id invalid_quantity invalid_service_type updated_since_not_supported invalid_request invalid_submission_id invalid_token insufficient_scope order_not_found product_not_found quote_product_not_found submission_not_found ordering_not_provisioned partner_order_id_reused quote_invalid rate_limit_exceeded internal_error service_unavailable

detail

required

Human-readable explanation. Do not parse this – it may be reworded without notice.

string

requestId

required

Echoes the request’s id. Include this when contacting Partner Integrations about a specific failed call – it resolves directly to one log entry.

string

Examples

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "code": "invalid_service_type",
  "detail": "\"serviceType\" must be one of STOCK, POD, got: DIGITAL. Only these two are orderable through this API.",
  "requestId": "8f3c1e2a-..."
}

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "code": "invalid_site_id",
  "detail": "site 99 is not granted to this partner",
  "requestId": "8f3c1e2a-..."
}

401

Missing, expired, or otherwise invalid credential. Not retryable as-is.

Produced by the API gateway’s authorizer, before the request reaches any application code, so every cause – no Authorization header, a malformed one, a token that is expired, wrongly signed, from the wrong pool, or belongs to a credential that has been disabled – yields this identical response. The gateway is configured to answer in the same application/problem+json shape as everything else, so you do not need a second parser for this status; what it cannot do is tell you which of those causes applied.

Media typeapplication/problem+json

RFC 9457 application/problem+json body. code is the published, stable, machine-readable field to branch your integration logic on – detail is a human-readable string that may be reworded over time and must not be parsed.

This table is the whole published set: every code this API can return appears below, and nothing below is unreachable. test/docs/openapi-matches-reality.test.ts compares the enum to the codes the handlers actually construct, so a code added to one side and not the other fails the build rather than shipping.

Published code values:

code	HTTP status	Meaning	Retry?
invalid_cursor	400	The cursor query parameter could not be decoded.	No – restart pagination with no cursor. Do not resend the same value.
invalid_site_id	400	The siteId filter is not a positive integer, or it names a site outside your grant. detail says which.	No – fix the parameter against GET /v1/me’s grantedSiteIds.
invalid_order_number	400	The order number in the path is not a positive integer.	No – fix the path.
invalid_product_id	400	The productId path segment on GET /v1/products/{productId} does not match the SLO_/SLS_-prefixed shape.	No – fix the path.
invalid_service_type	400	GET /v1/products’s serviceType filter is not one of the values this API can order (STOCK or POD).	No – fix the parameter.
updated_since_not_supported	400	An updatedSince parameter was sent. Rejected rather than ignored, on purpose – see “No updatedSince / no change polling” above.	No – remove the parameter; there is no change-polling mechanism to switch to.
invalid_request	400	POST /v1/orders’s request body failed validation – malformed JSON, a missing or malformed field, an unknown key, or a body-level rule such as partnerLineId uniqueness or a misplaced shipTo – or GET /v1/orders/submissions’s status/limit filter is malformed. detail names the exact violation.	No – fix the request.
invalid_submission_id	400	The submissionId path segment on GET /v1/orders/submissions/{submissionId} is not a well-formed UUID.	No – fix the path.
invalid_quantity	400	The quantity on POST /v1/products/{productId}/quote is missing or not a positive integer.	No – fix the request body.
invalid_token	401	The credential is missing, expired, or invalid.	No – mint a new token, retry once, then investigate the credential.
insufficient_scope	403	The token lacks the scope required for this operation.	No – mint a token with the required scope.
order_not_found	404	No such order, or one that exists outside your granted sites (see above).	No.
product_not_found	404	No such product, or one that exists but belongs to a site outside your granted sites (same rule as order_not_found).	No.
quote_product_not_found	404	The product resolved in our own catalog but Collaterate could not price it. Rare.	No.
submission_not_found	404	No submission exists with this id for your credential – whether it never existed or belongs to another partner, identically.	No.
ordering_not_provisioned	409	POST /v1/orders’s siteId has no ordering user configured. This is set up per (partner, site) by staff at onboarding; a partner cannot provision it themselves.	No – ask Partner Integrations to provision an ordering user for the site, then retry.
partner_order_id_reused	409	POST /v1/orders’s partnerOrderId was already used, with a request body that does not match this one. Resending the identical body under the same partnerOrderId is safe and returns the original submission (see the operation description); reusing it for a materially different order is rejected instead of silently creating a second order.	No – use a new partnerOrderId, or resend the exact original body to poll the existing submission.
quote_invalid	422	Collaterate rejected the quote on business-validation grounds (e.g. quantity over the product’s configured maximum). detail carries Collaterate’s own validation message.	No – fix the request body (e.g. reduce quantity).
rate_limit_exceeded	429	Rate limit or daily quota exceeded.	Yes – honor Retry-After.
internal_error	500	Unexpected server-side failure. Detail is always the fixed string below, never the underlying error.	No, or with caution – if persistent, contact Partner Integrations.
service_unavailable	503	Transient failure – typically the database path, but also a Lambda that crashed, timed out, or hit its own concurrency limit before any handler ran.	Yes, with backoff.

Three statuses are answered by the API gateway before your request reaches application code: 401 (authorizer denial), 429 (usage-plan throttle), and 503 (the Lambda integration itself failed). All three are configured to return this same document with the codes above, so one parser and one branch on code covers every error this API produces. The 403 on GET /v1/ping is the sole exception anywhere in the API – it comes from the edge firewall, which is not ours to shape, and carries no problem document.

object

type

required

Always the literal string about:blank today; reserved by RFC 9457 for future use.

string

Allowed value: about:blank

title

required

Short, human-readable summary of the HTTP status (e.g. “Not Found”).

string

status

required

The HTTP status code, repeated in the body for convenience.

integer

code

required

Stable, machine-readable error identifier. Safe to branch on. See the table above.

string

Allowed values: invalid_cursor invalid_site_id invalid_order_number invalid_product_id invalid_quantity invalid_service_type updated_since_not_supported invalid_request invalid_submission_id invalid_token insufficient_scope order_not_found product_not_found quote_product_not_found submission_not_found ordering_not_provisioned partner_order_id_reused quote_invalid rate_limit_exceeded internal_error service_unavailable

detail

required

Human-readable explanation. Do not parse this – it may be reworded without notice.

string

requestId

required

Echoes the request’s id. Include this when contacting Partner Integrations about a specific failed call – it resolves directly to one log entry.

string

Example

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "code": "invalid_token",
  "detail": "The credential presented with this request is missing, expired, or invalid.",
  "requestId": "8f3c1e2a-..."
}

403

The credential is valid but lacks the scope required for this operation (for example, a token minted without partner-api/orders:read). Not retryable as-is – request a token with the required scope. Not to be confused with an out-of-scope order, which is a 404 (see above), or with the edge firewall’s 403 on /ping, which carries no problem document at all.

Media typeapplication/problem+json

RFC 9457 application/problem+json body. code is the published, stable, machine-readable field to branch your integration logic on – detail is a human-readable string that may be reworded over time and must not be parsed.

This table is the whole published set: every code this API can return appears below, and nothing below is unreachable. test/docs/openapi-matches-reality.test.ts compares the enum to the codes the handlers actually construct, so a code added to one side and not the other fails the build rather than shipping.

Published code values:

code	HTTP status	Meaning	Retry?
invalid_cursor	400	The cursor query parameter could not be decoded.	No – restart pagination with no cursor. Do not resend the same value.
invalid_site_id	400	The siteId filter is not a positive integer, or it names a site outside your grant. detail says which.	No – fix the parameter against GET /v1/me’s grantedSiteIds.
invalid_order_number	400	The order number in the path is not a positive integer.	No – fix the path.
invalid_product_id	400	The productId path segment on GET /v1/products/{productId} does not match the SLO_/SLS_-prefixed shape.	No – fix the path.
invalid_service_type	400	GET /v1/products’s serviceType filter is not one of the values this API can order (STOCK or POD).	No – fix the parameter.
updated_since_not_supported	400	An updatedSince parameter was sent. Rejected rather than ignored, on purpose – see “No updatedSince / no change polling” above.	No – remove the parameter; there is no change-polling mechanism to switch to.
invalid_request	400	POST /v1/orders’s request body failed validation – malformed JSON, a missing or malformed field, an unknown key, or a body-level rule such as partnerLineId uniqueness or a misplaced shipTo – or GET /v1/orders/submissions’s status/limit filter is malformed. detail names the exact violation.	No – fix the request.
invalid_submission_id	400	The submissionId path segment on GET /v1/orders/submissions/{submissionId} is not a well-formed UUID.	No – fix the path.
invalid_quantity	400	The quantity on POST /v1/products/{productId}/quote is missing or not a positive integer.	No – fix the request body.
invalid_token	401	The credential is missing, expired, or invalid.	No – mint a new token, retry once, then investigate the credential.
insufficient_scope	403	The token lacks the scope required for this operation.	No – mint a token with the required scope.
order_not_found	404	No such order, or one that exists outside your granted sites (see above).	No.
product_not_found	404	No such product, or one that exists but belongs to a site outside your granted sites (same rule as order_not_found).	No.
quote_product_not_found	404	The product resolved in our own catalog but Collaterate could not price it. Rare.	No.
submission_not_found	404	No submission exists with this id for your credential – whether it never existed or belongs to another partner, identically.	No.
ordering_not_provisioned	409	POST /v1/orders’s siteId has no ordering user configured. This is set up per (partner, site) by staff at onboarding; a partner cannot provision it themselves.	No – ask Partner Integrations to provision an ordering user for the site, then retry.
partner_order_id_reused	409	POST /v1/orders’s partnerOrderId was already used, with a request body that does not match this one. Resending the identical body under the same partnerOrderId is safe and returns the original submission (see the operation description); reusing it for a materially different order is rejected instead of silently creating a second order.	No – use a new partnerOrderId, or resend the exact original body to poll the existing submission.
quote_invalid	422	Collaterate rejected the quote on business-validation grounds (e.g. quantity over the product’s configured maximum). detail carries Collaterate’s own validation message.	No – fix the request body (e.g. reduce quantity).
rate_limit_exceeded	429	Rate limit or daily quota exceeded.	Yes – honor Retry-After.
internal_error	500	Unexpected server-side failure. Detail is always the fixed string below, never the underlying error.	No, or with caution – if persistent, contact Partner Integrations.
service_unavailable	503	Transient failure – typically the database path, but also a Lambda that crashed, timed out, or hit its own concurrency limit before any handler ran.	Yes, with backoff.

Three statuses are answered by the API gateway before your request reaches application code: 401 (authorizer denial), 429 (usage-plan throttle), and 503 (the Lambda integration itself failed). All three are configured to return this same document with the codes above, so one parser and one branch on code covers every error this API produces. The 403 on GET /v1/ping is the sole exception anywhere in the API – it comes from the edge firewall, which is not ours to shape, and carries no problem document.

object

type

required

Always the literal string about:blank today; reserved by RFC 9457 for future use.

string

Allowed value: about:blank

title

required

Short, human-readable summary of the HTTP status (e.g. “Not Found”).

string

status

required

The HTTP status code, repeated in the body for convenience.

integer

code

required

Stable, machine-readable error identifier. Safe to branch on. See the table above.

string

Allowed values: invalid_cursor invalid_site_id invalid_order_number invalid_product_id invalid_quantity invalid_service_type updated_since_not_supported invalid_request invalid_submission_id invalid_token insufficient_scope order_not_found product_not_found quote_product_not_found submission_not_found ordering_not_provisioned partner_order_id_reused quote_invalid rate_limit_exceeded internal_error service_unavailable

detail

required

Human-readable explanation. Do not parse this – it may be reworded without notice.

string

requestId

required

Echoes the request’s id. Include this when contacting Partner Integrations about a specific failed call – it resolves directly to one log entry.

string

Example

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This request requires the \"partner-api/orders:read\" scope.",
  "requestId": "8f3c1e2a-..."
}

429

Your rate limit or daily quota was exceeded. Retryable – honor the Retry-After header (seconds) before your next attempt.

Like the 401, this comes from the gateway’s usage plan rather than from application code, and is configured to carry the same problem document as every other error so a single parser covers the whole API.

Media typeapplication/problem+json

RFC 9457 application/problem+json body. code is the published, stable, machine-readable field to branch your integration logic on – detail is a human-readable string that may be reworded over time and must not be parsed.

This table is the whole published set: every code this API can return appears below, and nothing below is unreachable. test/docs/openapi-matches-reality.test.ts compares the enum to the codes the handlers actually construct, so a code added to one side and not the other fails the build rather than shipping.

Published code values:

code	HTTP status	Meaning	Retry?
invalid_cursor	400	The cursor query parameter could not be decoded.	No – restart pagination with no cursor. Do not resend the same value.
invalid_site_id	400	The siteId filter is not a positive integer, or it names a site outside your grant. detail says which.	No – fix the parameter against GET /v1/me’s grantedSiteIds.
invalid_order_number	400	The order number in the path is not a positive integer.	No – fix the path.
invalid_product_id	400	The productId path segment on GET /v1/products/{productId} does not match the SLO_/SLS_-prefixed shape.	No – fix the path.
invalid_service_type	400	GET /v1/products’s serviceType filter is not one of the values this API can order (STOCK or POD).	No – fix the parameter.
updated_since_not_supported	400	An updatedSince parameter was sent. Rejected rather than ignored, on purpose – see “No updatedSince / no change polling” above.	No – remove the parameter; there is no change-polling mechanism to switch to.
invalid_request	400	POST /v1/orders’s request body failed validation – malformed JSON, a missing or malformed field, an unknown key, or a body-level rule such as partnerLineId uniqueness or a misplaced shipTo – or GET /v1/orders/submissions’s status/limit filter is malformed. detail names the exact violation.	No – fix the request.
invalid_submission_id	400	The submissionId path segment on GET /v1/orders/submissions/{submissionId} is not a well-formed UUID.	No – fix the path.
invalid_quantity	400	The quantity on POST /v1/products/{productId}/quote is missing or not a positive integer.	No – fix the request body.
invalid_token	401	The credential is missing, expired, or invalid.	No – mint a new token, retry once, then investigate the credential.
insufficient_scope	403	The token lacks the scope required for this operation.	No – mint a token with the required scope.
order_not_found	404	No such order, or one that exists outside your granted sites (see above).	No.
product_not_found	404	No such product, or one that exists but belongs to a site outside your granted sites (same rule as order_not_found).	No.
quote_product_not_found	404	The product resolved in our own catalog but Collaterate could not price it. Rare.	No.
submission_not_found	404	No submission exists with this id for your credential – whether it never existed or belongs to another partner, identically.	No.
ordering_not_provisioned	409	POST /v1/orders’s siteId has no ordering user configured. This is set up per (partner, site) by staff at onboarding; a partner cannot provision it themselves.	No – ask Partner Integrations to provision an ordering user for the site, then retry.
partner_order_id_reused	409	POST /v1/orders’s partnerOrderId was already used, with a request body that does not match this one. Resending the identical body under the same partnerOrderId is safe and returns the original submission (see the operation description); reusing it for a materially different order is rejected instead of silently creating a second order.	No – use a new partnerOrderId, or resend the exact original body to poll the existing submission.
quote_invalid	422	Collaterate rejected the quote on business-validation grounds (e.g. quantity over the product’s configured maximum). detail carries Collaterate’s own validation message.	No – fix the request body (e.g. reduce quantity).
rate_limit_exceeded	429	Rate limit or daily quota exceeded.	Yes – honor Retry-After.
internal_error	500	Unexpected server-side failure. Detail is always the fixed string below, never the underlying error.	No, or with caution – if persistent, contact Partner Integrations.
service_unavailable	503	Transient failure – typically the database path, but also a Lambda that crashed, timed out, or hit its own concurrency limit before any handler ran.	Yes, with backoff.

Three statuses are answered by the API gateway before your request reaches application code: 401 (authorizer denial), 429 (usage-plan throttle), and 503 (the Lambda integration itself failed). All three are configured to return this same document with the codes above, so one parser and one branch on code covers every error this API produces. The 403 on GET /v1/ping is the sole exception anywhere in the API – it comes from the edge firewall, which is not ours to shape, and carries no problem document.

object

type

required

Always the literal string about:blank today; reserved by RFC 9457 for future use.

string

Allowed value: about:blank

title

required

Short, human-readable summary of the HTTP status (e.g. “Not Found”).

string

status

required

The HTTP status code, repeated in the body for convenience.

integer

code

required

Stable, machine-readable error identifier. Safe to branch on. See the table above.

string

Allowed values: invalid_cursor invalid_site_id invalid_order_number invalid_product_id invalid_quantity invalid_service_type updated_since_not_supported invalid_request invalid_submission_id invalid_token insufficient_scope order_not_found product_not_found quote_product_not_found submission_not_found ordering_not_provisioned partner_order_id_reused quote_invalid rate_limit_exceeded internal_error service_unavailable

detail

required

Human-readable explanation. Do not parse this – it may be reworded without notice.

string

requestId

required

Echoes the request’s id. Include this when contacting Partner Integrations about a specific failed call – it resolves directly to one log entry.

string

Example

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "The request rate limit has been exceeded. Retry after the indicated delay.",
  "requestId": "8f3c1e2a-..."
}

Headers

Retry-After

integer

Seconds to wait before retrying.

500

An unexpected server-side failure. detail is always the fixed string below and never the underlying error – a database message quoted back to a partner is a disclosure, so nothing is interpolated into it. The requestId resolves to the log entry that does carry the cause; send it to Partner Integrations rather than guessing.

Media typeapplication/problem+json

RFC 9457 application/problem+json body. code is the published, stable, machine-readable field to branch your integration logic on – detail is a human-readable string that may be reworded over time and must not be parsed.

This table is the whole published set: every code this API can return appears below, and nothing below is unreachable. test/docs/openapi-matches-reality.test.ts compares the enum to the codes the handlers actually construct, so a code added to one side and not the other fails the build rather than shipping.

Published code values:

code	HTTP status	Meaning	Retry?
invalid_cursor	400	The cursor query parameter could not be decoded.	No – restart pagination with no cursor. Do not resend the same value.
invalid_site_id	400	The siteId filter is not a positive integer, or it names a site outside your grant. detail says which.	No – fix the parameter against GET /v1/me’s grantedSiteIds.
invalid_order_number	400	The order number in the path is not a positive integer.	No – fix the path.
invalid_product_id	400	The productId path segment on GET /v1/products/{productId} does not match the SLO_/SLS_-prefixed shape.	No – fix the path.
invalid_service_type	400	GET /v1/products’s serviceType filter is not one of the values this API can order (STOCK or POD).	No – fix the parameter.
updated_since_not_supported	400	An updatedSince parameter was sent. Rejected rather than ignored, on purpose – see “No updatedSince / no change polling” above.	No – remove the parameter; there is no change-polling mechanism to switch to.
invalid_request	400	POST /v1/orders’s request body failed validation – malformed JSON, a missing or malformed field, an unknown key, or a body-level rule such as partnerLineId uniqueness or a misplaced shipTo – or GET /v1/orders/submissions’s status/limit filter is malformed. detail names the exact violation.	No – fix the request.
invalid_submission_id	400	The submissionId path segment on GET /v1/orders/submissions/{submissionId} is not a well-formed UUID.	No – fix the path.
invalid_quantity	400	The quantity on POST /v1/products/{productId}/quote is missing or not a positive integer.	No – fix the request body.
invalid_token	401	The credential is missing, expired, or invalid.	No – mint a new token, retry once, then investigate the credential.
insufficient_scope	403	The token lacks the scope required for this operation.	No – mint a token with the required scope.
order_not_found	404	No such order, or one that exists outside your granted sites (see above).	No.
product_not_found	404	No such product, or one that exists but belongs to a site outside your granted sites (same rule as order_not_found).	No.
quote_product_not_found	404	The product resolved in our own catalog but Collaterate could not price it. Rare.	No.
submission_not_found	404	No submission exists with this id for your credential – whether it never existed or belongs to another partner, identically.	No.
ordering_not_provisioned	409	POST /v1/orders’s siteId has no ordering user configured. This is set up per (partner, site) by staff at onboarding; a partner cannot provision it themselves.	No – ask Partner Integrations to provision an ordering user for the site, then retry.
partner_order_id_reused	409	POST /v1/orders’s partnerOrderId was already used, with a request body that does not match this one. Resending the identical body under the same partnerOrderId is safe and returns the original submission (see the operation description); reusing it for a materially different order is rejected instead of silently creating a second order.	No – use a new partnerOrderId, or resend the exact original body to poll the existing submission.
quote_invalid	422	Collaterate rejected the quote on business-validation grounds (e.g. quantity over the product’s configured maximum). detail carries Collaterate’s own validation message.	No – fix the request body (e.g. reduce quantity).
rate_limit_exceeded	429	Rate limit or daily quota exceeded.	Yes – honor Retry-After.
internal_error	500	Unexpected server-side failure. Detail is always the fixed string below, never the underlying error.	No, or with caution – if persistent, contact Partner Integrations.
service_unavailable	503	Transient failure – typically the database path, but also a Lambda that crashed, timed out, or hit its own concurrency limit before any handler ran.	Yes, with backoff.

Three statuses are answered by the API gateway before your request reaches application code: 401 (authorizer denial), 429 (usage-plan throttle), and 503 (the Lambda integration itself failed). All three are configured to return this same document with the codes above, so one parser and one branch on code covers every error this API produces. The 403 on GET /v1/ping is the sole exception anywhere in the API – it comes from the edge firewall, which is not ours to shape, and carries no problem document.

object

type

required

Always the literal string about:blank today; reserved by RFC 9457 for future use.

string

Allowed value: about:blank

title

required

Short, human-readable summary of the HTTP status (e.g. “Not Found”).

string

status

required

The HTTP status code, repeated in the body for convenience.

integer

code

required

Stable, machine-readable error identifier. Safe to branch on. See the table above.

string

Allowed values: invalid_cursor invalid_site_id invalid_order_number invalid_product_id invalid_quantity invalid_service_type updated_since_not_supported invalid_request invalid_submission_id invalid_token insufficient_scope order_not_found product_not_found quote_product_not_found submission_not_found ordering_not_provisioned partner_order_id_reused quote_invalid rate_limit_exceeded internal_error service_unavailable

detail

required

Human-readable explanation. Do not parse this – it may be reworded without notice.

string

requestId

required

Echoes the request’s id. Include this when contacting Partner Integrations about a specific failed call – it resolves directly to one log entry.

string

Example

{
  "type": "about:blank",
  "title": "Internal Server Error",
  "status": 500,
  "code": "internal_error",
  "detail": "An unexpected error occurred.",
  "requestId": "8f3c1e2a-..."
}

503

Transient failure in the service or the database it reads from (for example, the Aurora reader could not be reached in time), or the request never reached application code at all because the Lambda behind it crashed, timed out, or hit its own concurrency limit. Retryable, with backoff.

Media typeapplication/problem+json

RFC 9457 application/problem+json body. code is the published, stable, machine-readable field to branch your integration logic on – detail is a human-readable string that may be reworded over time and must not be parsed.

This table is the whole published set: every code this API can return appears below, and nothing below is unreachable. test/docs/openapi-matches-reality.test.ts compares the enum to the codes the handlers actually construct, so a code added to one side and not the other fails the build rather than shipping.

Published code values:

code	HTTP status	Meaning	Retry?
invalid_cursor	400	The cursor query parameter could not be decoded.	No – restart pagination with no cursor. Do not resend the same value.
invalid_site_id	400	The siteId filter is not a positive integer, or it names a site outside your grant. detail says which.	No – fix the parameter against GET /v1/me’s grantedSiteIds.
invalid_order_number	400	The order number in the path is not a positive integer.	No – fix the path.
invalid_product_id	400	The productId path segment on GET /v1/products/{productId} does not match the SLO_/SLS_-prefixed shape.	No – fix the path.
invalid_service_type	400	GET /v1/products’s serviceType filter is not one of the values this API can order (STOCK or POD).	No – fix the parameter.
updated_since_not_supported	400	An updatedSince parameter was sent. Rejected rather than ignored, on purpose – see “No updatedSince / no change polling” above.	No – remove the parameter; there is no change-polling mechanism to switch to.
invalid_request	400	POST /v1/orders’s request body failed validation – malformed JSON, a missing or malformed field, an unknown key, or a body-level rule such as partnerLineId uniqueness or a misplaced shipTo – or GET /v1/orders/submissions’s status/limit filter is malformed. detail names the exact violation.	No – fix the request.
invalid_submission_id	400	The submissionId path segment on GET /v1/orders/submissions/{submissionId} is not a well-formed UUID.	No – fix the path.
invalid_quantity	400	The quantity on POST /v1/products/{productId}/quote is missing or not a positive integer.	No – fix the request body.
invalid_token	401	The credential is missing, expired, or invalid.	No – mint a new token, retry once, then investigate the credential.
insufficient_scope	403	The token lacks the scope required for this operation.	No – mint a token with the required scope.
order_not_found	404	No such order, or one that exists outside your granted sites (see above).	No.
product_not_found	404	No such product, or one that exists but belongs to a site outside your granted sites (same rule as order_not_found).	No.
quote_product_not_found	404	The product resolved in our own catalog but Collaterate could not price it. Rare.	No.
submission_not_found	404	No submission exists with this id for your credential – whether it never existed or belongs to another partner, identically.	No.
ordering_not_provisioned	409	POST /v1/orders’s siteId has no ordering user configured. This is set up per (partner, site) by staff at onboarding; a partner cannot provision it themselves.	No – ask Partner Integrations to provision an ordering user for the site, then retry.
partner_order_id_reused	409	POST /v1/orders’s partnerOrderId was already used, with a request body that does not match this one. Resending the identical body under the same partnerOrderId is safe and returns the original submission (see the operation description); reusing it for a materially different order is rejected instead of silently creating a second order.	No – use a new partnerOrderId, or resend the exact original body to poll the existing submission.
quote_invalid	422	Collaterate rejected the quote on business-validation grounds (e.g. quantity over the product’s configured maximum). detail carries Collaterate’s own validation message.	No – fix the request body (e.g. reduce quantity).
rate_limit_exceeded	429	Rate limit or daily quota exceeded.	Yes – honor Retry-After.
internal_error	500	Unexpected server-side failure. Detail is always the fixed string below, never the underlying error.	No, or with caution – if persistent, contact Partner Integrations.
service_unavailable	503	Transient failure – typically the database path, but also a Lambda that crashed, timed out, or hit its own concurrency limit before any handler ran.	Yes, with backoff.

Three statuses are answered by the API gateway before your request reaches application code: 401 (authorizer denial), 429 (usage-plan throttle), and 503 (the Lambda integration itself failed). All three are configured to return this same document with the codes above, so one parser and one branch on code covers every error this API produces. The 403 on GET /v1/ping is the sole exception anywhere in the API – it comes from the edge firewall, which is not ours to shape, and carries no problem document.

object

type

required

Always the literal string about:blank today; reserved by RFC 9457 for future use.

string

Allowed value: about:blank

title

required

Short, human-readable summary of the HTTP status (e.g. “Not Found”).

string

status

required

The HTTP status code, repeated in the body for convenience.

integer

code

required

Stable, machine-readable error identifier. Safe to branch on. See the table above.

string

Allowed values: invalid_cursor invalid_site_id invalid_order_number invalid_product_id invalid_quantity invalid_service_type updated_since_not_supported invalid_request invalid_submission_id invalid_token insufficient_scope order_not_found product_not_found quote_product_not_found submission_not_found ordering_not_provisioned partner_order_id_reused quote_invalid rate_limit_exceeded internal_error service_unavailable

detail

required

Human-readable explanation. Do not parse this – it may be reworded without notice.

string

requestId

required

Echoes the request’s id. Include this when contacting Partner Integrations about a specific failed call – it resolves directly to one log entry.

string

Example

{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "code": "service_unavailable",
  "detail": "The service is temporarily unavailable. Please retry.",
  "requestId": "8f3c1e2a-..."
}