Legacy

Upgrade your SDK without migrating from usage records Legacy

Call legacy UsageRecords APIs with RawRequest and a pinned Stripe API version.

The Basil SDK release deprecated the UsageRecords API and meter-less metered Prices. If you need to upgrade your SDK to adopt features unrelated to metered billing, you can continue calling the legacy UsageRecords API by pinning to a pre-Basil API version via RawRequest. This lets you upgrade your SDK without disrupting your metered billing integration.

This is a temporary workaround, not a migration path. Your subscriptions remain in classic billing mode. To migrate your integration to billing meters, follow the migration guide.

Prerequisites

Your SDK version must support RawRequest .
Your Prices have recurring.usage_type=metered and no recurring.meter value set. This means that you’re reporting usage through the UsageRecords API, not Billing Meters.

Report usage

POST /v1/subscription_items/{id}/usage_records

Use this call to report metered usage for a subscription item. Stripe aggregates these records to calculate what your customer owes at invoice time.

Required parameters: quantity, timestamp, action ( set or increment)

client.raw_request(
 "post",
 f"/v1/subscription_items/{subscription_item_id}/usage_records",
 stripe_version="2025-02-24.acacia",
 quantity=100,
 timestamp=1234567890,
 action="increment",
)

Read usage record summaries

GET /v1/subscription_items/{id}/usage_record_summaries

Use this call to retrieve aggregated usage for a subscription item over a billing period. Useful for displaying current consumption to your customers or reviewing usage before an invoice is finalized.

client.raw_request(
 "get",
 f"/v1/subscription_items/{subscription_item_id}/usage_record_summaries",
 stripe_version="2025-02-24.acacia",
)

Create a Subscription with a legacy metered price

POST /v1/subscriptions

Use this call to create a subscription that includes a legacy metered price with recurring.usage_type=metered and no Billing Meter. Starting with the Basil API version, this request is blocked without a pinned API version.

client.raw_request(
 "post",
 "/v1/subscriptions",
 stripe_version="2025-02-24.acacia",
 customer="cus_xxx",
 **{
 "items[0][price]": "price_xxx",
 "payment_behavior": "default_incomplete",
 "payment_settings[save_default_payment_method]": "on_subscription",
 }
)

Update a Subscription with a legacy metered price

POST /v1/subscriptions/{id}

Use this call to modify an existing subscription that includes a legacy metered price, for example, to add a new metered price item or swap an existing one. This request is blocked on Basil and later without a pinned API version.

client.raw_request(
 "post",
 f"/v1/subscriptions/{subscription_id}",
 stripe_version="2025-02-24.acacia",
 **{
 "items[0][price]": "price_xxx",
 }
)