REST API overview

The Distribu REST API lets you read and write your company's data programmatically. Every feature you can use through the dashboard or storefront has a data model behind it, and most of those models are reachable over HTTPS.

What you can do today

• Read your products — full catalog, one at a time or paginated.
• Read your orders — all of them, filtered by status, customer, or date range.
• Create orders — the same server-side semantics as a storefront order (decrements stock, fires webhooks, etc.) but without needing a customer to log in.
• Update order status — move orders through the lifecycle programmatically.
• Manage customers — list, read, create, and update customer records.
• Pull reports — sales, customer-spend, and inventory valuation as structured JSON.
• Manage webhook endpoints — register new subscriptions, change the event list, disable, or delete — from code.

What's not exposed over the API (yet):

• Inventory adjustments outside of order placement
• Products write (create/update/delete) — read-only today
• API key management
• Returns, refunds, and credit notes — dashboard / storefront only
• Webhook secret rotation and delivery-log access

If any of those are blocking you, email support@distribu.app — we prioritize API coverage based on what's actually slowing customers down.

Base URL

Everything is served under /api/v1/ on your Distribu domain:

https://distribu.app/api/v1/

The v1 prefix is a commitment: we won't break existing endpoints within the v1 namespace. Future additions go through v1 too. If we ever need to make breaking changes, they'd land on v2 and v1 would keep working alongside it.

A minimal request

Every API call needs an Authorization: Bearer <key> header. Everything else is optional:

curl https://distribu.app/api/v1/products \
  -H "Authorization: Bearer dk_YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "clxx1234...",
      "name": "Widget Blue",
      "sku": "WDG-001",
      "category": "Hardware",
      "unit": "each",
      "price": 8.5,
      "stock": 42,
      "isActive": true,
      "createdAt": "2026-03-01T12:00:00.000Z",
      "updatedAt": "2026-04-10T09:30:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

Response shape

All list endpoints wrap results in { data: [...], pagination: {...} }. All single-resource endpoints wrap in { data: {...} }. All errors wrap in { error: "message" } with an appropriate HTTP status. See Errors for the full catalog.

Content types

• Requests — JSON only. Content-Type: application/json on any request with a body.
• Responses — Always JSON with Content-Type: application/json.
• No form-encoded requests. Don't send application/x-www-form-urlencoded.

Authentication at a glance

Create an API key from Settings → API keys. Keys look like dk_... and can't be retrieved after creation — copy them once. Each key is scoped to a specific company and carries one or more permissions.

See Authentication for the full flow and Scopes for the permission model.

Rate limits

60 requests per minute per API key. Exceeding it returns 429 Too Many Requests with a retryAfter field indicating how many seconds to wait.

{
  "error": "Rate limit exceeded. Try again shortly.",
  "retryAfter": 42
}

Limits are per-key, not per-company, so splitting a workload across multiple keys raises your ceiling linearly. If you're consistently bumping against 60/min, email us — this is a starting value, not a hard cap.

Idempotency

There is no idempotency key mechanism today. If the network fails mid-request on POST /api/v1/orders, you don't have a safe way to retry — you could end up with a duplicate order.

Workaround: after a failed POST, GET /api/v1/orders?customerId={id} sorted by createdAt desc and look for a recent match before retrying. An idempotency-key header is on the roadmap.

Endpoints in this section

• Authentication — creating keys, the Bearer header, key lifecycle.
• Scopes — the 9 scope values and which endpoints they gate.
• Pagination — cursor-based pagination, limit parameter, looping through results.
• Errors — every status code and error message the API can return.
• Products endpoints — the product read endpoints.
• Orders endpoints — list, create, single, and status update endpoints for orders.
• Customers endpoints — list, read, create, and update customers.
• Reports endpoints — sales, customer-spend, and inventory valuation as JSON.
• Webhooks endpoints — manage webhook subscriptions programmatically.

Related

• Webhooks — the push-side complement to the API.
• Audit log — every API-key-driven action is recorded with the key's ID as the actor.

Next: Authentication.