Skip to main content

​
Base URL

Send JSON and read 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:
  • 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.
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:
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. 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.

​
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.