Integrate subscriptions with your stack
Every touchpoint between your systems and Bolt Subscriptions, and when you need each one.
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 | Shopper to Bolt | Every plan |
| Usage events | Your servers to Bolt | Usage-based plans |
| Catalog API | Your servers to Bolt | Optional: managing products and plans in code |
| 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.
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. Create the order token shows the full request; send your division's publishable key in the
X-Publishable-Keyheader alongside the API key. Reference the plan by settingsubscription_plan_idon the cart item. Bolt creates the subscription from the completed order.
"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 schedule. On other stores, usage plans are invoiced for the shopper to pay unless every charge model on the plan is capped.
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 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
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 for the endpoints and worked requests.
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 for endpoint registration and usage alerts for that event's payload.