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

# Making requests

> Base URL, safe retries, pagination and money

## Base URL

```text theme={null}
https://bouclay.com/api/v1
```

Send JSON and read JSON:

```http theme={null}
Authorization: Bearer sk_test_…
Accept: application/json
Content-Type: application/json
```

Every successful response puts the object, or the list, in `data`, and the request's id in `meta.requestId`. Quote that id when you write to support.

## Safe retries with idempotency keys

A network error can leave you unsure whether a request went through. Retrying blindly could create two customers or charge twice. An **idempotency key** prevents that: it is a unique string you make up for each write, and Bouclay remembers what it answered.

Every `POST` and `PATCH` must send an `Idempotency-Key` header:

```bash theme={null}
curl https://bouclay.com/api/v1/customers \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: signup-user-42" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.com", "name": "Ada Obi"}'
```

* **Same key, same request:** Bouclay replays the first response. Nothing happens twice.
* **Same key, different body or endpoint:** refused with `409 idempotency_conflict`.
* **New key:** a new request.

Use a key that names the action, such as `signup-user-42` or `subscribe-user-42-pro`, so a double-click or a retry reuses it. Don't use a timestamp alone.

> [!NOTE]
>
> A few endpoints dedupe on their own and need no key: meter events use their `identifier`, and committing or releasing a credit hold is safe to repeat.

## Pagination

Lists return up to `limit` items and a cursor for the next page:

```bash theme={null}
curl "https://bouclay.com/api/v1/customers?limit=25&after=ctm_…" \
  -H "Authorization: Bearer $BOUCLAY_KEY"
```

```json theme={null}
{
  "data": [],
  "meta": {
    "requestId": "req_…",
    "pagination": { "hasMore": true, "previous": "ctm_…", "next": "ctm_…" }
  }
}
```

Pass `meta.pagination.next` as `after` to get the next page, or `previous` as `before` to go back. Use one of `after` or `before`, not both. An unknown cursor returns `400 invalid_cursor`.

## Money

Amounts are in **major units** of the currency: `15000` means ₦15,000, not ₦150.

Bouclay keeps exact minor units (kobo, cents) inside and rounds half up once, at the end. A usage price can even cost less than a kobo a unit by quoting its rate per a number of units. See [Usage billing](https://docs.bouclay.com/billing/usage-billing.md#pricing-per-a-number-of-units).

Currencies are three-letter ISO codes such as `NGN`, `USD`, `KES` or `GHS`. Which ones you can charge depends on your gateway. See [Connect a gateway](https://docs.bouclay.com/gateways/connect.md).

## Your own data on objects

Most objects take `customData`, a JSON object you can fill with your own ids and notes. Bouclay stores it and returns it, and never reads it. Customers also take `externalRef`, your own id for them, which meter events accept in place of the Bouclay id.

## Rate limits

Each API key can make up to 100 requests per second. Past that, requests get `429 rate_limited`, and the `Retry-After` header says how many seconds to wait. Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining` so you can slow down before you reach the limit.


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