Skip to content
Collaterate Partner API

Collaterate Partner API

The Partner API gives you access to the Collaterate sites you have been granted: read the orders on them, browse what they can sell, and place new orders against them. Everything is filtered to your grant, and every capability is gated by a scope on your credential.

What you want to do Where it starts
Read orders, shipments and line items GET /v1/orders, keyset paginated, plus /shipments and /items on each
Find something you can order GET /v1/products - every active variant, with orderable saying which
Place an order POST /v1/orders, then poll the submission it returns
Get a price POST /v1/products/{productId}/quote
Be told when an order changes signed webhooks, registered by Collaterate on request
Drive all of it from an AI agent POST /v1/mcp

Two more endpoints tell you where you stand: GET /v1/me describes your own credential and lists your granted sites, and GET /v1/ping answers without one.

Not everything is available to everyone - which endpoints answer for you depends on the scopes your credential carries. GET /v1/me is the authoritative answer for your own access.

Pick your host before anything else

Section titled “Pick your host before anything else”

Machine integrations are onboarded onto 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.

Bearer tokenapi.partners.collaterate.com

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.

Mutual TLSmtls.partners.collaterate.com

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.

There is also a third method, for people rather than services. If you are one of a partner’s own staff pointing an MCP client at this API, you can sign in interactively as yourself instead of holding either credential above - same bearer host, same resulting identity and scopes. See MCP for that, and Authentication for all three flows in full, including the certificate onboarding sequence.

Where to go next

Section titled “Where to go next”

Start with these three:

  • 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 all three schemes, how your scopes are resolved, and credential rotation.
  • Your first order is the end-to-end walkthrough: pick a product from the catalog, quote it, submit the order, and follow it to shipment.

Then, roughly in the order an integration needs them:

  • Tenancy and access explains what you can see, why an order outside your grant returns 404 rather than 403, and how quickly a change to your grant takes effect.
  • Catalog and products covers paging the full active catalog, what visibility and orderable each tell you, why you key it on (productId, variantId), and how artworkSource decides what an order line carries.
  • 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 null SKU means.
  • Submitting orders covers POST /v1/orders: the fast path, idempotency on partnerOrderId, and which failures are terminal.
  • Webhooks covers the signed, best-effort notifications sent when an order changes, and how to verify one.
  • 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.
  • Versioning sets out what can change inside v1 without notice, and what your client must therefore tolerate.
  • Pricing covers quoting a product, and the customer discount a quote cannot see.

Two ways to avoid writing a client by hand:

  • SDK (TypeScript) is a typed client you install with npm, using the same credential you already hold.
  • MCP (agentic access) points an AI agent - Claude Code, Gemini CLI, Kiro, VS Code, or your own framework - at the same API, with tools narrowed to your scopes.

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.

Currentv1 reference

Every endpoint, parameter, schema and response for v1, served under the base path /v1 on whichever host you authenticate against. Generating a client instead? Download the raw OpenAPI document for v1.

Environments

Section titled “Environments”

Every host on this site is the production one. There are two environments, identical in shape and differing only in domain:

Environment Bearer host mTLS host
Production api.partners.collaterate.com mtls.partners.collaterate.com
Test / sandbox api.partners.collaterail.com mtls.partners.collaterail.com

Substitute collaterail.com for collaterate.com in any example on this site to address the sandbox - the path, the payload and the behavior are the same.

Credentials are per-environment. A sandbox client id will not authenticate against production, and grants are configured separately in each. Your Partner Integrations contact will tell you which you have been given access to.

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.