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

# REST API Overview

Welcome to Salesbricks' public API: the gateway to seamless access and management of your customers, subscriptions, invoices, and usage.

The **REST API (v2)** is the recommended way to integrate with Salesbricks. It covers the full subscription lifecycle: creating customers, starting subscriptions, taking payment, upgrading, and reporting on revenue.

<Note>
  **A note on our legacy GraphQL API:**

  Our [GraphQL API (v1)](/api-reference/getting-started/graphql) remains fully supported for existing
  integrations.

  For new work, we recommend the REST API. It receives all new functionality,
  including the self-serve and product-led growth endpoints described below.
</Note>

<Card title="Browse the REST API endpoints" icon="code" href="/api-reference/customers/list-all-customers">
  Full endpoint reference with an interactive playground.
</Card>

## Base URL

All REST requests target:

| Environment | Base URL |
| - | - |
| Production | `https://api.salesbricks.com/api/v2` |
| Staging | `https://api.staging.salesbricks.com/api/v2` |

## Authentication

Every request must include your **Public API Token** in the `X-SALESBRICKS-KEY` header.

<Tip>
  See the [Authentication](/api-reference/getting-started/authentication) guide to find your token.
</Tip>

## Your first request

List the customers belonging to your seller account:

```bash cURL theme={null}
curl https://api.salesbricks.com/api/v2/customers \
  -H "X-SALESBRICKS-KEY: <your-api-key>"
```

### Example Response

```json JSON theme={null}
{
  "count": 123,
  "next": "https://api.salesbricks.com/api/v2/customers?offset=100&limit=100",
  "previous": null,
  "results": [
    {
      "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "Acme Corp",
      "legal_name": "Acme Corporation",
      "external_id": "crm-account-001",
      "subscriptions": []
    }
  ]
}
```

## What you can build

<CardGroup cols={2}>
  <Card title="Start subscriptions" icon="rocket-launch" href="/api-reference/getting-started/starting-a-subscription">
    Create a customer and take them through checkout, signature, or a direct server-side start.
  </Card>

  <Card title="Let customers self-serve" icon="gear" href="/api-reference/manage-my-subscription">
    Generate a billing portal link so customers can change plans and payment methods.
  </Card>

  <Card title="Report usage" icon="tally" href="/api-reference/usage/overview">
    Submit metered usage for usage-based bricks.
  </Card>

  <Card title="React to events" icon="webhook" href="/api-reference/webhooks/overview">
    Receive webhooks when orders complete, invoices are paid, and more.
  </Card>
</CardGroup>

## Pagination

List endpoints are paginated with the `limit` and `offset` query parameters, and return a `count` alongside `next` and `previous` URLs. `next` and `previous` are `null` when there is no further page in that direction.

```bash cURL theme={null}
curl "https://api.salesbricks.com/api/v2/customers?limit=25&offset=50" \
  -H "X-SALESBRICKS-KEY: <your-api-key>"
```

## Errors

Errors return a standard shape containing a machine-readable `code` and a human-readable `message`.

```json JSON theme={null}
{
  "error": {
    "code": "ERR_BAD_REQUEST",
    "message": "Bad request — the input payload is malformed, missing required fields, or contains invalid data."
  }
}
```

| Status | Meaning |
| - | - |
| `400` | The payload is malformed, missing required fields, or violates a business rule. |
| `404` | The resource does not exist, or is not visible to your API token. |

<Tip>
  For write endpoints, send an idempotency key so retries are safe. See [Idempotent
  Requests](/api-reference/getting-started/idempotent-requests).
</Tip>

Let's dive in! 🚀


## Related topics

- [Overview](/api-reference/usage/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.