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

# How Bouclay fits together

> The objects you work with, and how money moves from a plan to a paid invoice

Most of the API is a handful of objects. Once you know how they connect, every endpoint reads naturally.

## The objects

| Object | ID prefix | What it is |
| - | - | - |
| **Customer** | `ctm_` | Someone who pays you. Store their id against your own user. |
| **Product** | `prod_` | Something you sell, such as "Inkwell". |
| **Plan** | `plan_` | A named tier of a product that customers pick, such as "Pro" or "Team". |
| **Charge** | `chg_` | One part of a plan: a platform fee, seats, or one kind of usage. Most plans have one. |
| **Price** | `price_` | What a charge costs in one currency and billing interval. Prices never change once used; you create a new one instead. |
| **Meter** | `mtr_` | Something your app counts, such as API calls or SMS sent. |
| **Subscription** | `sub_` | A customer on one or more plans, billed every period. |
| **Invoice** | `inv_` | What a customer owes for a period or a one-off charge. Issued invoices never change. |
| **Payment** | `pay_` | One attempt to collect an invoice through your gateway. |
| **Credit note** | `cn_` | A correction to an issued invoice: a refund, or credit kept for later. |
| **Credit grant** | `cg_` | A lot of credit a customer can spend: promotional or prepaid. |
| **Event** | `evt_` | Something that changed, sent to your webhook endpoints. |

## How a subscription bills

**1. You build the catalog once**

A product holds plans. Each plan holds one or more charges, and each charge has a price per currency and interval. See [Catalog](https://docs.bouclay.com/billing/catalog.md).

**2. A customer subscribes**

A subscription takes every active charge of the plan. A trial starts at once; otherwise the first invoice is issued straight away.

**3. Bouclay issues an invoice each period**

Fixed fees are billed at the start of the period. Usage is counted from meter events and billed when the period ends.

**4. Bouclay collects it**

With `collectionMode: automatic`, Bouclay charges the customer's saved card through your gateway. With `manual`, the customer pays the invoice by bank transfer or on its hosted page.

**5. If a payment fails, Bouclay retries**

The subscription turns `past_due`, the customer gets emails, and Bouclay retries on your schedule. See [Failed payments](https://docs.bouclay.com/billing/failed-payments.md).

**6. Your app hears about every change**

Every change fires a webhook. Read the object's `status` and update your app. See [Webhooks](https://docs.bouclay.com/integrate/webhooks.md).

## Test mode and live mode

Test keys (`sk_test_…`) charge through your gateway's test account, and live keys (`sk_live_…`) through its live account. Saved cards belong to one mode: a test key can never reach a live card. See [Going live](https://docs.bouclay.com/get-started/go-live.md).

## Money is in major units

The API sends and receives amounts in major units: `5000` is ₦5,000, not 50 naira. Bouclay keeps exact minor units inside and rounds once, at the end. See [Money](https://docs.bouclay.com/integrate/requests.md#money).

## Early access features

Some features are documented before they are turned on for every account: usage billing, tiered pricing, entitlements, discounts, credit holds, metrics, the cancellation flow, plan retirement, routing between gateways, and the Paystack, Flutterwave and Nomba gateways. They carry an **Early access** badge in the API reference. Until a feature is on for your account, its endpoints answer `404 not_found` and its fields are refused with a `422`. Write to [hello@bouclay.com](mailto:hello@bouclay.com) to have one turned on. Nothing you already use changes when it is.


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