> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> The StateSet One API — base URL, authentication, your first request, errors, and pagination.

# StateSet One API

StateSet One is the commerce operating system underneath orders, inventory, returns, logistics,
and finance. Everything the platform does is available over this API.

This page is the contract: how to authenticate, what a response looks like, and what happens when
something goes wrong.

## Base URL

```
https://api.stateset.com/v1
```

## Authenticate

Every request needs an API key in the `Authorization` header.

```bash theme={null}
curl https://api.stateset.com/api/v1/orders \
  -H "Authorization: Bearer $STATESET_API_KEY"
```

API keys, JWT tokens, and OAuth 2.0 are all supported — see
[Authentication](/api-reference/authentication) for when to use which.

<Warning>
  Treat a key as a credential for your whole account. Keep it server-side, never in browser or
  mobile code, and issue a separate key per consumer so you can revoke one without breaking
  everything else.
</Warning>

## Your first request

List recent orders:

```bash theme={null}
curl "https://api.stateset.com/api/v1/orders?limit=5" \
  -H "Authorization: Bearer $STATESET_API_KEY"
```

Create one:

```bash theme={null}
curl -X POST https://api.stateset.com/api/v1/orders \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customer_id": "cus_1042",
    "line_items": [{ "sku": "SHOE-RED-10", "quantity": 1 }]
  }'
```

<Note>
  Send an `Idempotency-Key` on every write. A retried request with the same key replays the original
  result instead of creating a second order — which matters more than usual when an agent is doing
  the retrying.
</Note>

## Errors

Failures return a structured envelope, not a bare string:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "type": "error_type",
    "details": { },
    "request_id": "req_1NXWPnCo6bFb1KQto6C8OWvE",
    "timestamp": "2024-01-15T10:30:00Z",
    "documentation_url": "https://docs.stateset.com/errors/ERROR_CODE"
  }
}
```

Branch on `code`, not on `message` — messages are for humans and may be reworded. Log
`request_id`; it's what support needs to trace a specific call.

Full catalogue in [Errors](/api-reference/errors).

## Rate limits

Responses carry your current budget:

| Header                  | Meaning                           |
| ----------------------- | --------------------------------- |
| `X-RateLimit-Limit`     | Requests allowed in the window    |
| `X-RateLimit-Remaining` | Requests left                     |
| `X-RateLimit-Reset`     | When the window resets            |
| `X-RateLimit-Retry`     | How long to wait after a `429`    |
| `X-RateLimit-Bucket`    | Which bucket the limit applies to |

Read `X-RateLimit-Remaining` and back off before you're throttled rather than after. Details in
[Rate limiting](/api-reference/rate-limiting).

## Beyond REST

| Interface                                       | Use for                                                     |
| ----------------------------------------------- | ----------------------------------------------------------- |
| **GraphQL** — queries, mutations, subscriptions | Fetching exactly the shape you need, and live subscriptions |
| **[gRPC](/api-reference/grpc-framework)**       | Low-latency service-to-service calls                        |
| **[Webhooks](/api-reference/webhooks)**         | Reacting to events instead of polling                       |
| **[Events](/api-reference/events)**             | The event catalogue                                         |

GraphQL supports **remote data joins**, so a single query can span sources that live in different
systems.

## What the platform covers

| Domain                   | Endpoints                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| Orders and checkout      | [Order management](/api-reference/orders/list) · [Checkouts](/api-reference/checkouts/list)                              |
| Returns and warranties   | [Returns](/api-reference/return/list) · [Warranties](/api-reference/warranty/list)                                       |
| Inventory and warehouse  | [Inventory](/api-reference/inventory/get) · [Packing lists](/api-reference/packinglist/list)                             |
| Manufacturing            | [BOM](/api-reference/billofmaterials/list) · [Work orders](/api-reference/workorder/list)                                |
| Suppliers and purchasing | [Purchase orders](/api-reference/purchaseorders/list) · [Suppliers](/api-reference/suppliers/list)                       |
| CRM                      | [Leads](/api-reference/leads/list) · [Accounts](/api-reference/accounts/list) · [Contacts](/api-reference/contacts/list) |

Workflow orchestration runs on [Temporal](/api-reference/temporal), so long-running operations are
durable rather than best-effort.

## SDKs

Official clients wrap auth, retries, and pagination — see [SDKs](/api-reference/sdks).

## Next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/api-reference/quickstart">
    A working request in a few minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Keys, JWT, and OAuth 2.0.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    Every code and what to do about it.
  </Card>

  <Card title="Integrations" icon="plug" href="/api-reference/integrations">
    186 native integrations.
  </Card>
</CardGroup>