Overview

Collaterate Partner API 1

Read-only API for partners to retrieve their own order data from Collaterate.

Scoping and the 404-vs-403 rule

Every partner is granted a specific set of siteIds. All reads are scoped to those sites at the database layer. An order that exists but belongs to a site you are not granted returns 404 order_not_found – never 403. This is deliberate: a 403 would confirm the order exists in a site you cannot see, and this API never confirms that. If you see a 404 for an order number you expected to find, the two indistinguishable causes are “no such order” and “not one of your sites” – there is no way to tell these apart from the response, by design.

No `updatedSince` / no change polling

This API does not offer an updatedSince filter, and none should be inferred from the updatedOn field on an order. An audit of the underlying data found that orders.updatedOn does not move when a shipment, tracking number, or item quantity changes on an existing order (25.6% of orders have a child record newer than the order itself), and a separate internal process can move an order into your site without updating that column either. Treating it as a watermark would silently hide real changes.

GET /v1/orders is therefore ordered by placedOn (set once, at order creation, and genuinely monotonic), which is safe to paginate over but cannot be used to detect that an existing order changed status or shipped. Do not build a polling loop keyed on updatedOn – it will miss changes.

What you can do is poll a specific order. GET /v1/orders/{orderNumber}/shipments always reflects current state, so the supported pattern for tracking is: discover new orders by paginating GET /v1/orders, keep your own list of the ones not yet delivered, and re-request that endpoint for each of them on your own schedule. What is missing is only the ability to ask which orders changed – not the ability to see current state for one you already know about.

Retry guidance

Retry, with backoff: 429 (honor the Retry-After header) and 503.
Do not retry as-is: 400, 401, 403, 404, 409 – these mean the request itself needs to change (fix the input, fix the credential, accept that the resource is not visible to you, or – for 409 on POST /v1/orders – fix the site’s provisioning or the reused partnerOrderId). Retrying unchanged will get you the same response every time.

Information

License: Proprietary
OpenAPI version: 3.1.0

Authentication

oauth2

Client Credentials grant against POST /oauth2/token on this same host. Request the scope(s) you need in the scope parameter, space-separated, prefixed with the resource server identifier partner-api/ (for example partner-api/orders:read).

Credentials may be sent either in the form body or as HTTP Basic in an Authorization header. The endpoint is unversioned, unlike every other path here, because its request and response are RFC 6749’s rather than ours.

Security scheme type: oauth2

Flow type: clientCredentials

Token URL: https://api.partners.collaterate.com/oauth2/token

Scopes:

partner-api/orders:read - Read orders for your granted sites.
partner-api/orders:write - Submit orders and poll their submission status.
partner-api/sites:read - Read the list of sites granted to you.
partner-api/products:read - Read the product catalog for your granted sites.

oauth2AuthorizationCode

Authorization Code + PKCE, for a partner’s own staff signing in interactively (for example, from an MCP client like Claude Code, Gemini CLI, or Kiro) rather than a machine credential. Discoverable via GET /.well-known/oauth-authorization-server; clients that speak Dynamic Client Registration (RFC 7591) may POST /oauth2/register to obtain the client_id rather than hardcoding it.

authorization_endpoint and token_endpoint below are on this same host – not Cognito’s – for the same portability reason POST /oauth2/token is proxied for the client-credentials flow.

Security scheme type: oauth2

Flow type: authorizationCode

Authorization URL: https://api.partners.collaterate.com/oauth2/authorize

Token URL: https://api.partners.collaterate.com/oauth2/user-token

Scopes:

partner-api/orders:read - Read orders for your granted sites.
partner-api/orders:write - Submit orders and poll their submission status.
partner-api/sites:read - Read the list of sites granted to you.
partner-api/products:read - Read the product catalog for your granted sites.

mtls

Some partners are onboarded with mutual TLS instead of OAuth2, against the separate mtls.partners.collaterate.com host rather than api.partners.collaterate.com. Your client certificate is presented on the TLS handshake; there is no bearer token and no token endpoint on this path. This is arranged individually during onboarding – contact Partner Integrations if you are unsure which method applies to you.

Security scheme type: mutualTLS