Getting started with the Supplier API

Connect the systems a supplier already runs, an ERP, a warehouse management system, a courier integration, straight to the purchase orders Orbit stores send you. The Supplier API is a small, purpose-built REST surface: pull orders, acknowledge them, ship parcels, push tracking and stock, and subscribe to signed webhooks. It is authenticated with a key you mint yourself in the supplier dashboard. No partner account, no plugin, no OAuth.

Who this is for

Orbit Commerce has two API surfaces for two different businesses:

If you are integrating a store's own systems, read Store API keys instead. If you build software that many stores install, start at Getting started with plugins. Everything on this page and the guides beside it is for suppliers.

Creating a key

In the supplier dashboard, open Settings, then API Keys, and choose Create API key. Creating keys needs the supplier permission to manage settings, so an owner or an admin does this.

1. Name it after the system that will hold it. "Warehouse WMS connector", "Sage 200 sync". The name is how you tell keys apart later.
2. Pick scopes. A key can only call the endpoints its scopes cover. Grant the least the system needs.
3. Set an expiry if you want one. Keys are long-lived by default and stay valid until revoked. An expiry must be in the future.
4. Copy the key immediately. It is shown exactly once. Orbit stores only a fingerprint, so a lost key cannot be recovered, only revoked and replaced.

Keys look like sup_sk_ followed by 43 characters. The dashboard shows the first twelve characters of each key so you can match a key in your configuration to a row in the list. A supplier can hold up to 10 active keys, which is enough for one per connected system with room to rotate.

The four scopes

Scopes narrow the key, not the supplier. A key holding every scope can do exactly what the dashboard can do on these surfaces, nothing more.

Making your first call

Send the key as a bearer token. The supplier is derived from the key itself, so there is no supplier or store identifier to pass.

GET /api/supplier-api/v1/orders?status=sent&limit=20 HTTP/1.1
Host: api.myorbitcommerce.net
Authorization: Bearer sup_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

const response = await fetch(
  'https://api.myorbitcommerce.net/api/supplier-api/v1/orders?status=sent&limit=20',
  { headers: { Authorization: `Bearer ${process.env.ORBIT_SUPPLIER_API_KEY}` } },
);
const { data } = await response.json(); // { items, meta }

Every successful response arrives in the platform's standard envelope. Read the data field; the shapes documented in these guides are what you find inside it.

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "items": [ ... ],
    "meta": { "page": 1, "limit": 20, "total": 3, "totalPages": 1, "statusCounts": { "sent": 3 } }
  },
  "timestamp": "2026-09-07T09:01:20.963Z"
}

A POST that creates something answers 201 with "message": "Created"; everything else answers 200, and a queued redelivery answers 202.

The endpoints

All paths are relative to https://api.myorbitcommerce.net/api/supplier-api/v1.

The scope column omits the supplier_api: prefix for space; the full strings are in the table above. Request and response fields for every endpoint are in the Supplier API Reference, and the walkthroughs cover the behaviour that a schema cannot: Purchase orders and shipments, Stock updates, Webhooks, and Idempotency, rate limits and errors.

Key lifecycle

Revocation is immediate. Revoking a key in the dashboard takes effect on its next request. There is no cache to wait out. If a key may have leaked, revoke first and rewire after.

Scopes are fixed at creation. There is deliberately no way to widen a live key, because that would silently escalate a credential some system already holds. To change access, create a new key with the scopes you want, switch the system over, and revoke the old one.

Rotation is a recipe, not a mechanism. Keys do not rotate themselves. Create the successor, deploy it, confirm traffic, revoke the predecessor. Two keys can be live side by side for as long as the migration needs.

Webhooks belong to the key that created them. A subscription created through the API is owned by that key. Revoking the key deletes its subscriptions, and a key that reaches its expiry date stops its subscriptions delivering. Recreate them with the replacement key as part of the rotation. Subscriptions created in the dashboard are owned by the supplier and are unaffected. See Webhooks.

Watch last used. The key list shows when each key last made a call, updated at most once a minute. A key whose activity you cannot account for should simply be revoked.

Security practices

• Server-side only. A key in a browser, a mobile app or a public repository is public. Keep it in your server's secret manager or environment.
• One key per system. Separate keys for the ERP and the warehouse mean revoking one does not break the other.
• Least scopes. A job that only reads orders needs supplier_api:orders:read, not orders:write.
• Never log it. Redact the key from request logs and error reports. The sup_sk_ prefix makes it easy to scan for.

Next steps

• Pull orders, acknowledge them, and ship: Purchase orders and shipments.
• Get told when an order arrives instead of polling: Webhooks.
• Every request and response shape: Supplier API Reference.