Skip to main content
The Bachs API is organized around REST. It uses predictable resource-oriented URLs, accepts and returns JSON, and relies on standard HTTP verbs and status codes. Every endpoint in this reference follows the conventions on this page, so you only need to learn them once.

​
Base URL

All requests go to a versioned base URL. The current version is v1. The sandbox is fully isolated from production. Data, keys, and charges created there never affect real money. See Sandbox.

​
Authentication

Every request must include your secret key in the Authorization header as a Bearer token.
Use sk_sandbox_... keys against the sandbox base URL and sk_live_... keys against production. Keys are scoped: a key can only call the endpoints its scopes permit. A request with a missing or invalid key returns 401; a valid key without the required scope returns 403. See Authentication and Permissions.
Never expose secret keys in client-side code, public repositories, or logs. Rotate a key immediately if it is compromised.

​
Request format

Send request bodies as JSON with a Content-Type: application/json header. Set Accept: application/json to receive JSON responses.
A few conventions hold across every endpoint:
  • Money is a decimal string. Amounts are sent and returned as strings with two decimal places in the currency’s major unit: "29.00" for $29.00, "75000.00" for ₦75,000.00. Never send a number, and never use minor units (cents).
  • Timestamps are ISO 8601. All dates and times are UTC strings, e.g. "2026-04-27T12:00:00Z".
  • IDs are prefixed strings. Every resource ID carries a type prefix, e.g. prod_... for products, cust_... for customers, chk_... for checkout sessions. Treat IDs as opaque; do not parse them.

​
Response format

Successful responses return a JSON object with an HTTP 2xx status. Single-resource endpoints return the resource object directly. Endpoints that return a list wrap results in items alongside a pagination object. See Success responses and Pagination.

​
HTTP status codes

Bachs uses conventional HTTP status codes to indicate the result of a request. In general, 2xx means success, 4xx means the request was rejected for a reason you can fix, and 5xx means something went wrong on our side. Every 4xx response carries a machine-readable error_code you can branch on. See Errors for the shape and the full error code reference.

​
Query parameters

List endpoints accept query parameters to filter and page through results. Parameters are simple key/value pairs appended to the URL.
Common conventions:
  • Pagination. List endpoints accept a limit (max 100; values above are clamped, not rejected) and page with either a cursor or an offset, depending on the endpoint. Each endpoint’s reference page states its default limit and which paging style it uses. See Pagination.
  • Booleans. Pass true or false, e.g. include_archived=true.
  • Unknown parameters are ignored. An unrecognized query parameter does not error; it is silently dropped.

​
Idempotency

Public POST and PATCH requests under /v1/ support an Idempotency-Key header. Successful responses are cached for matching retries; a timeout or 5xx still requires outcome reconciliation. DELETE is not covered by this middleware. See Idempotency.

​
Rate limits

Requests are rate limited per API key, so each key has its own budget. Every response includes headers describing your current budget: If you exceed the limit you receive a 429 Too Many Requests. Read Retry-After and wait that many seconds before retrying.