# Sell prepaid usage credits with Checkout

Let customers buy prepaid credits for an existing Metronome contract.

Let your customers buy prepaid usage credits through Stripe. You set the default credit options and discount rules, while [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) provides the payment form, processes the payment, and coordinates post-payment steps with [Metronome](https://docs.stripe.com/billing/usage-based.md). This means you don’t need to build and maintain a separate payment flow, and you can accept global payments.

### Get early access to Metronome credit purchases with Checkout

Enter your email to request access.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/payments/checkout/metronome-credit-purchases" \
  -d '{"email": "EMAIL", "preview": "metronome_checkout_preview"}'
```

## How usage credit purchases work

A [Metronome commit](https://docs.metronome.com/guides/pricing-packaging/apply-credits-and-commits/create-a-pre-paid-commit) is a credit purchase. The customer pays an invoice amount and receives an access amount that credits them for usage.

For each purchase, Checkout:

1. Collects payment from the customer.
2. Creates the prepaid commit on the specified [Metronome contract](https://docs.metronome.com/guides/get-started/how-metronome-works#contracts%E2%80%8B) after payment succeeds.
3. Emits a `checkout.session.completed` event with the relevant payment details.
4. Orchestrates commit creation and the respective webhook in Metronome.

## Before you begin

- Use [API version](https://docs.stripe.com/api/versioning.md) `2026-09-30.preview`. Set `Stripe-Version: 2026-09-30.preview` for direct HTTP requests.
- Review the private preview [limitations](https://docs.stripe.com/payments/checkout/metronome-credit-purchases.md#limitations).
- Create a [Customer](https://docs.stripe.com/api/customers/create.md) to store your customer’s payment methods.
- [Configure your Metronome workspace](https://docs.metronome.com/guides/get-started/metronome-dashboard-quickstart).
- [Verify your product entity mappings](https://docs.metronome.com/integrations/invoice-integrations/stripe#create-optional-entity-mapping-rules). If you don’t create a mapping, Stripe creates a Stripe product on your behalf during each transaction. In this case, we use the default tax code on your Stripe account.

## Configure usage credits

Configure your usage credits:

- `commit_options`: Specify a predefined list of credit amounts for a customer to choose from. You can optionally allow the customer to enter a custom amount. You can also configure volume-based discounts that reduce the amount charged based on the number of credits purchased.
- `access_schedule`: Specify a fixed payment amount and one or more schedule items that make credits available during predefined time periods.

For each commit, you must use either `commit_options` or `access_schedule`, not both.

## Choose your UI

This private preview supports Checkout full hosted page and embedded form. When you create your Checkout Session, set `ui_mode` to `hosted_page` or `form`. If you omit `ui_mode`, the Checkout Session defaults to `hosted_page`.

Select a tab to see the UI for `commit_options`:

#### Full hosted page
![Buying prepaid credits in the full hosted page](https://b.stripecdn.com/docs-statics-srv/assets/metronome-hosted.f212d211b41f4803b66eb1c53c24bc71.png)

Buying prepaid credits in the full hosted page

#### Embedded form
![Buying prepaid credits in the embedded form](https://b.stripecdn.com/docs-statics-srv/assets/metronome-embedded-form.22b59d0c30b0a4ef4079594ee7d8579f.png)

Buying prepaid credits in the embedded form

## Create a Checkout Session

Create a Checkout Session with one item whose type is `metronome_commit`. A Checkout Session item can contain multiple commits, but all commits must use the same Metronome contract. The Checkout Session item is immutable after creation.

The following request lets customers select a predefined credit amount or enter a custom amount. It applies a 20% volume discount to purchases of at least 500 USD in credits. It also enables [Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md) to display prices in local currencies and [Stripe Tax](https://docs.stripe.com/tax.md) to calculate tax automatically:

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.preview" \
  -d ui_mode=hosted_page \
  --data-urlencode "success_url=https://example.com/checkout/complete?session_id={CHECKOUT_SESSION_ID}" \
  -d customer={{CUSTOMER_ID}} \
  -d "adaptive_pricing[enabled]=true" \
  -d "automatic_tax[enabled]=true" \
  -d "items[0][type]=metronome_commit" \
  -d "items[0][metronome_commit][metronome_contract]={{METRONOME_CONTRACT_ID}}" \
  -d "items[0][metronome_commit][price_configuration][currency]=usd" \
  -d "items[0][metronome_commit][price_configuration][tax_behavior]=exclusive" \
  -d "items[0][metronome_commit][commits][0][name]=Additional AI credits" \
  -d "items[0][metronome_commit][commits][0][description]=Credits purchased during the current contract term" \
  -d "items[0][metronome_commit][commits][0][metronome_product]={{METRONOME_PRODUCT_ID}}" \
  -d "items[0][metronome_commit][commits][0][tax_details][tax_code]=txcd_10103000" \
  --data-urlencode "items[0][metronome_commit][commits][0][commit_options][starting_at]=2027-01-01T00:00:00Z" \
  --data-urlencode "items[0][metronome_commit][commits][0][commit_options][ending_before]=2028-01-01T00:00:00Z" \
  -d "items[0][metronome_commit][commits][0][commit_options][discount_tiers][0][up_to]=49999" \
  -d "items[0][metronome_commit][commits][0][commit_options][discount_tiers][0][discount_percentage]=0" \
  -d "items[0][metronome_commit][commits][0][commit_options][discount_tiers][1][up_to]=inf" \
  -d "items[0][metronome_commit][commits][0][commit_options][discount_tiers][1][discount_percentage]=20" \
  -d "items[0][metronome_commit][commits][0][commit_options][options][0][access_amount]=10000" \
  -d "items[0][metronome_commit][commits][0][commit_options][options][1][access_amount]=50000" \
  -d "items[0][metronome_commit][commits][0][commit_options][options][1][default_option]=true" \
  -d "items[0][metronome_commit][commits][0][commit_options][custom_amount][enabled]=true" \
  -d "items[0][metronome_commit][commits][0][commit_options][custom_amount][minimum]=100" \
  -d "items[0][metronome_commit][commits][0][commit_options][custom_amount][maximum]=10000000"
```

The timestamps must be RFC 3339 strings in UTC, aligned to hour boundaries.

Checkout displays each commit as a separate line item and calculates the payment amount from the selected access amount and matching discount tier. The tier’s discount applies to the entire selected access amount. A discount tier applies its percentage to the entire selected access amount. Exactly one tier must use `"up_to": "inf"`.

### Custom pricing units

The example above uses fiat credits, but you can also sell credits in a [custom pricing unit](https://docs.metronome.com/guides/pricing-packaging/make-pricing-changes/use-currency-custompricingunits#set-currencies-and-custom-pricing-units). For both `commit_options` and `access_schedule`, specify access amounts according to the credit type:

- **Fiat credits:** Omit `credit_type_id` and express access amounts in the smallest unit of the currency specified by `price_configuration.currency`. For example, 10000 represents 100.00 USD.
- **Custom pricing units:** Set `credit_type_id` to the Metronome credit type ID, and express access amounts as native credit counts, not fiat amounts.

### Collect tax automatically

To collect tax automatically with `automatic_tax.enabled=true`, first [set up Stripe Tax](https://docs.stripe.com/tax/set-up.md). Set `tax_behavior` to `inclusive` or `exclusive`, or configure an account-level default. If the commits use different tax codes, set `tax_details.tax_code` separately for each commit. For more details, see [Automatically collect tax with Checkout](https://docs.stripe.com/tax/checkout/page.md).

## Redirect the customer to Checkout

Submit the purchase to your server endpoint. The endpoint creates the Checkout Session and returns a `303` redirect to `session.url`. Keep the API call on your server and load your secret key from an environment variable or secrets manager.

```js
app.post('/create-checkout-session', async (req, res) => {
  const session = await stripe.checkout.sessions.create(
    buildMetronomeCheckoutSessionParams(req),
    {apiVersion: '2026-09-30.preview'}
  );

  res.redirect(303, session.url);
});
```

In this example, `buildMetronomeCheckoutSessionParams` returns the parameters from the generated request.

> Don’t grant credits when you receive `checkout.session.completed`. With [asynchronous payment methods](https://docs.stripe.com/payments/payment-methods.md#payment-notification), this event can arrive before payment succeeds and before the Metronome commit exists. Wait for the `commit.create` webhook from Metronome before granting credits.

## Grant access after commit creation

Use Metronome’s `commit.create` webhook as the entitlement signal for both synchronous and asynchronous payment methods. Use the Metronome API to retrieve the customer’s current credit balance.

## Create a multi-segment access schedule

Metronome supports commits with distinct access schedules, the customer gets a portion of the total access amount across each period. Use `access_schedule` instead of `commit_options` to support credit release on a predefined schedule. The two properties are mutually exclusive.

```json
{
 "name": "Annual AI credits",
 "metronome_product": "b0cdf8c8-f506-4c2a-b4df-5200a6ab7a0f",
 "access_schedule": {
   "price_amount": 50000,
   "schedule_items": [
     {
       "amount": 20000,
       "starting_at": "2027-01-01T00:00:00Z",
       "ending_before": "2027-04-01T00:00:00Z"
     },
     {
       "amount": 30000,
       "starting_at": "2027-04-01T00:00:00Z",
       "ending_before": "2028-01-01T00:00:00Z"
     }
   ]
 }
}
```

`price_amount` is the amount the customer pays in the smallest unit of `price_configuration.currency`. Each schedule item defines the credits available during its time window.

## Test your integration

Create the Checkout Session in a [sandbox](https://docs.stripe.com/sandboxes.md). Stripe routes the corresponding commit request to your Metronome sandbox.

Test the following use cases:

- A [synchronous payment method](https://docs.stripe.com/payments/payment-methods.md#payment-notification) (such as a credit card) succeeds and tax is correctly applied. Verify that the Metronome commit matches the values selected in Checkout.
- An [asynchronous payment method](https://docs.stripe.com/payments/payment-methods.md#payment-notification) (such as ACH) remains pending and your integration doesn’t grant access from `checkout.session.completed`.
- If payment fails, Metronome doesn’t create a commit.
- A customer selects the minimum and maximum custom access amounts.

## Limitations

This private preview has the following limitations.

### Unsupported features

- Metronome [customer creation](https://docs.metronome.com/guides/customers-billing/manage-customers/provision-a-customer#create-a-customer) and [contract creation](https://docs.metronome.com/guides/customers-billing/manage-customers/provision-a-customer#provision-a-customer-contract)
- [Contract upgrades, downgrades, and add-ons](https://docs.metronome.com/guides/pricing-packaging/make-pricing-changes/edit-or-override-a-contract), and [seat changes](https://docs.metronome.com/guides/pricing-packaging/subscription/provision-your-customer#seat-based-credit-pool)
- [Card installments](https://docs.stripe.com/payments/installments.md)
- [Card brand filtering](https://docs.stripe.com/payments/checkout/customization/card-brands.md)
- [Cross-sells](https://docs.stripe.com/payments/checkout/cross-sells.md) and [optional items](https://docs.stripe.com/payments/checkout/optional-items.md)
- [Surcharging](https://docs.stripe.com/payments/checkout/surcharge/automatic-surcharge.md)
- [Managed Payments](https://docs.stripe.com/payments/managed-payments.md)
- [Manual and dynamic tax rates](https://docs.stripe.com/payments/checkout/use-manual-tax-rates.md)
- [Customer-applied promotion codes and coupons in Checkout](https://docs.stripe.com/payments/checkout/discounts.md)
- [Recurring commit schedules](https://docs.metronome.com/guides/pricing-packaging/apply-credits-and-commits/create-a-pre-paid-commit#provision-recurring-usage-credits)

### Unsupported payment methods

Checkout filters out the following payment methods if you pass them to the Checkout Session:

- [ACSS Debit](https://docs.stripe.com/payments/acss-debit.md)
- [Konbini](https://docs.stripe.com/payments/konbini.md)
- [Swish](https://docs.stripe.com/payments/swish.md)
- [Vipps](https://docs.stripe.com/payments/vipps.md)

### Unsupported payment method options

This preview doesn’t support `payment_method_options` for the following payment methods. If you pass these options to the Checkout Session, Checkout filters out both the corresponding payment method and its options:

- [ACSS Debit](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-acss_debit)
- [Bacs Debit](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-bacs_debit)
- [BLIK](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-blik)
- [Customer Balance](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-customer_balance)
- [Konbini](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-konbini)
- [Klarna](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-klarna)
- [Pay by Bank](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-pay_by_bank)
- [PayPal](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-paypal)
- [PayTo](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-payto)
- [Pix](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-pix)
- [SEPA Debit](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-sepa_debit)
- [UPI](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-upi)
- [US Bank Account](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-us_bank_account)

## See also

- [Metronome](https://docs.metronome.com/guides/get-started/home)
- [Create a Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md)