Bolt has moved to boltapp.com. Stores still using bolt.com hosts must update now: see the migration guide.

Skip to content

Integrate subscriptions with your stack

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

View As MarkdownMCP

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.

TouchpointDirectionNeeded for
CheckoutShopper to BoltEvery plan
Usage eventsYour servers to BoltUsage-based plans
Catalog APIYour servers to BoltOptional: managing products and plans in code
WebhooksBolt to your serversOptional: 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-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.
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 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.

On this page