Migrate to billing meters

Learn how to migrate from usage records to billing meters.

Stripe is deprecating usage-records billing. Moving forward, you can migrate to billing meters, our only solution for usage-based billing. Billing meters provide the following advantages:

High-throughput usage reporting
One-hour reporting grace period for generating invoices
Collect usage before creating a subscription

However, we don’t support the following feature:

max aggregation formula

You can continue to use usage records as you adopt billing meters.

Billing meter overview

Billing meters allow you to track usage of a particular event. It supports high-throughput event ingestion and aggregation.

Unlike usage records, billing meters don’t require customers to have subscriptions before reporting usage and a single meter can track usage across multiple customers.

Learn more about billing meters in our implementation guide.

Create a meter

Create a billing meter. Learn more about configuring meters.

Create a new price

Create a new price associated with the billing meter. Make sure that the new price is on the same product as your old price.

Start recording usage

Note

You must continue to send usage records to Stripe until the migration is completed.

Start reporting usage to the Billing Meter API. Stripe doesn’t reflect this usage on customer invoices until they’re subscribed to the new price.

Learn more about recording usage.

OptionalQuery reported usage

Plan subscription schedules

Use subscription schedules to automatically migrate to the new price at the end of the billing cycle. Learn more about subscription schedules.

List the subscriptions associated with the old price.

Stripe returns a list of subscriptions associated with the old price. For example:

{
  "object": "list",
  "data": [
    {
      "id": "sub_1P1Y6gDxxK6kAaV0rS7ojBjh"
,
      "object": "subscription",
      ...
      "items": {
        "object": "list",
        "data": [
          {
            "id": "si_PrGdqMmuM1DGbQ"
,
            "object": "subscription_item",
            ...
            "price": {
              "id": "{{OLD_PRICE_ID}}",
              "object": "price",
              ...
              "recurring": {
                "aggregate_usage": "sum",
                "interval": "month",
                "interval_count": 1,
                "trial_period_days": null,
                "usage_type": "metered"
              },
              ...
            },
            ...
          }
        ],
        ...
      },
      ...
      "schedule": {
        "id": "sub_sched_1P1XxjDxxK6kAaV0YygN4tf7"
,
        "object": "subscription_schedule",
        ...
        "current_phase": {
          "end_date": 1714759200,
          "start_date": 1712167200
        },
        ...
        "phases": [
          {
            ...
            "end_date": 1714759200,
            ...
            "items": [
              {
                ...
                "price": "{{OLD_PRICE_ID}}",
                ...
              }
            ],
            ...
            "start_date": 1712167200,
            ...
            "trial_end": 1712772000
          }
        ],
        ...
      },
      ...
    },
    ...
  ],
  "has_more": false,
  "url": "/v1/subscriptions"
}

If a subscription has a schedule, you must update the existing subscription schedule to migrate to the new price at the end of a billing cycle. If no schedule exists for a subscription, create a new one.

Create a subscription schedule for each subscription associated with the old price.

Stripe returns a new subscription schedule object:

{
  "id": "sub_sched_1P1H37DxxK6kAaV0Iggc537m"
,
  "object": "subscription_schedule",
  ...
  "current_phase": {
    "end_date": 1714693634,
    "start_date": 1712101634
  },
  ...
  "phases": [
    {
      ...
      "end_date": 1714693634,
      ...
      "items": [
        {
          ...
          "price": "{{OLD_PRICE_ID}}",
          ...
        }
      ],
      ...
      "start_date": 1712101634,
      ...
    }
  ],
  ...
  "status": "active",
  ...
}

Update the subscription schedule to add a phase with the new price.

Test the migration

Create a test customer with a subscription associated with the old price.

Navigate to the Customers tab.
Click + Add customer.
Enter the name of the customer.
Navigate to the new customer.
Next to the Subscriptions header, click + to open the subscription drawer.
Select the old price.
Click Create test subscription.

Create a subscription schedule from the subscription.

Add a phase to the subscription schedule to migrate to the new price.

Simulate the subscription change with a test clock.

Learn more about testing subscriptions integrations. You can use test clocks to test different scenarios, including mock usage reporting. Learn more about test clocks.