# Integrate subscriptions with your stack

> Every touchpoint between your systems and Bolt Subscriptions, and when you need each one.

Source: https://help.boltapp.com/products/bolt-subscriptions/integration

Bolt runs the billing. Your systems connect to it at up to four points. Flat plans need only the first. Usage-based plans need the first two.

| Touchpoint                                 | Direction            | Needed for                                    |
| ------------------------------------------ | -------------------- | --------------------------------------------- |
| [Checkout](#connect-checkout)              | Shopper to Bolt      | Every plan                                    |
| [Usage events](#report-usage)              | Your servers to Bolt | Usage-based plans                             |
| [Catalog API](#manage-the-catalog-via-api) | Your servers to Bolt | Optional: managing products and plans in code |
| [Webhooks](#listen-to-webhooks)            | Bolt to your servers | Optional: reacting to subscription events     |

All server-side calls authenticate with your API and publishable keys from **Administration** > **API** in the dashboard. See [API keys](/getting-started/api-keys).

## Connect checkout [#connect-checkout]

Bolt creates a subscription from a completed checkout whose cart references the plan. There are two ways to connect checkout:

* **Hosted checkout link**: every plan on a product created with a SKU has a Bolt-hosted checkout link. The link identifies the product by its SKU. Copy it from the plan and place it behind your subscribe buttons. No code is required.
* **Your own checkout**: build the cart yourself, following the [Custom Cart guide](/custom-cart/overview). [Create the order token](/custom-cart/create-order-token) shows the full request; send your division's publishable key in the `X-Publishable-Key` header alongside the API key. Reference the plan by setting `subscription_plan_id` on the cart item. Bolt creates the subscription from the completed order.

```json title="Cart items"
"items": [
  {
    "name": "API plan, Base",
    "reference": "plan-base",
    "quantity": 1,
    "unit_price": 3000,
    "total_amount": 3000,
    "subscription_plan_id": "spl_u5QEiwSdZv4K"
  }
]
```

Whatever the plan type, the plan ID is enough: Bolt prices the plan line from the plan at checkout and again at every renewal, replacing any amounts sent on the line. For usage-based plans, each period's invoice carries the plan's base price plus the rated usage. On Bolt Cart, Bolt charges that invoice to the saved card automatically and retries on your [payment recovery](/products/bolt-subscriptions/set-up-flat-plan#configure-payment-recovery) schedule. On other stores, usage plans are invoiced for the shopper to pay unless every charge model on the plan is capped.

## Report usage [#report-usage]

Usage-based plans require your servers to report consumption to `POST /v1/usage_events`. Events are batched, deduplicated on your `merchant_event_id`, and validated individually. The [ingestion reference](/products/bolt-subscriptions/usage-events) has the full contract, limits, and every rejection reason. Connect this before the first billing period closes. Usage that is never reported is never billed.

## Manage the catalog via API [#manage-the-catalog-via-api]

Everything the dashboard does to products and plans is also an API: create products with plans, list them, and read subscriptions. Follow the [implementation guide](/api-reference/guides/subscriptions) for the endpoints and worked requests.

## Listen to webhooks [#listen-to-webhooks]

Bolt notifies your endpoint about subscription events, including `subscription_usage_alert` when a metered total crosses a threshold you set. Handlers must be idempotent: delivery is at least once. See [webhooks](/developers/webhooks) for endpoint registration and [usage alerts](/products/bolt-subscriptions/usage-alerts) for that event's payload.

## Related [#related]

* [Set up a flat plan](/products/bolt-subscriptions/set-up-flat-plan)
* [Set up a usage-based plan](/products/bolt-subscriptions/set-up-usage-based-plan)
* [Implementation guide](/api-reference/guides/subscriptions)
