Collaterate Partner API
The Partner API gives you read access to orders for the Collaterate sites you have been granted. It is read-only: there are no write endpoints in this version.
GET /v1/orders lists orders across your granted sites, keyset paginated.
GET /v1/orders/{orderNumber} fetches one. Two sub-resources carry the detail an integration
usually needs next: GET /v1/orders/{orderNumber}/shipments gives you shipments and tracking
numbers, and GET /v1/orders/{orderNumber}/items gives you line items with SKUs. Two more
endpoints exist to tell you where you stand: GET /v1/me describes your own credential, and
GET /v1/ping answers without one.
Pick your host before anything else
Section titled “Pick your host before anything else”You are onboarded onto exactly one of two authentication methods, and each has its own
hostname. Sending a bearer token to the mTLS host, or a client certificate to the bearer
host, fails as a bare 401 that says nothing about the host being wrong. This is the single
most common first-day mistake.
OAuth2 client_credentials against Cognito. You hold a client id and
secret, mint a short-lived access token, and send it in Authorization.
This is how most partners are set up.
Your client certificate is presented during the TLS handshake. There is no token and no token endpoint on this path. Arranged individually during onboarding.
If you are not sure which applies to you: if you were given a client secret, you are on the bearer path. See Authentication for both flows in full, including the certificate onboarding sequence.
Where to go next
Section titled “Where to go next”- Getting started walks from credential to a correct pagination loop, and covers the two response details that cost partners the most debugging time later.
- Authentication covers both schemes, how your scopes are resolved, and credential rotation.
- Tracking and line items covers the two order
sub-resources: the tracking precedence rule, the invariant that tells you when to stop
polling, and what a
nullSKU means. - Tenancy and access explains what you can see, why an order
outside your grant returns
404rather than403, and how quickly a change to your grant takes effect. - Errors documents the RFC 9457 problem document, every code the service returns, and which of them are worth retrying.
- Rate limits and quotas covers the per-partner tiers and the separate per-IP backstop above them.
Reference
Section titled “Reference”The reference is generated from the OpenAPI document this service is built against. Each API
version is documented separately and permanently: /docs/v1/ keeps working after v2 ships,
because your integration does too.
Every endpoint, parameter, schema and response for v1, served under the base path /v1 on whichever host you authenticate against.
Environments
Section titled “Environments”The hostnames above are production. Non-production environments are the same shape on a different domain, and your Partner Integrations contact will tell you which you have been given access to.
| Environment | Bearer host | mTLS host |
|---|---|---|
| Production | api.partners.collaterate.com |
mtls.partners.collaterate.com |
| Staging | api.partners.collaterail.com |
mtls.partners.collaterail.com |
| Test | api.partners.test-b-collaterate.net |
mtls.partners.test-b-collaterate.net |
Credentials are per-environment. A staging client id will not authenticate against production, and grants are configured separately in each.
Getting help
Section titled “Getting help”Every error the service returns carries a requestId. Include it when you contact Partner
Integrations about a specific failed call: it resolves to one log entry, which is much faster
than a search by approximate timestamp.