How rate card subscriptions workPrivate preview

When you set up usage-based billing with rate cards, you can use those rate cards as the basis for your customers’ subscriptions.

Rate card subscription concepts

Here are the key concepts for understanding how rate card subscriptions work.

Billing cadence and service interval

The billing cadence defines when invoices are generated. The generated invoice consolidates charges that have accrued during one or more service intervals. You can configure different billing cadences to match your business model and pricing structures.

When a service interval ends, Stripe calculates charges based on usage during that period (for example, a customer’s usage for the past week). These charges are added to the customer’s account but aren’t necessarily billed immediately.

When a billing cadence ends, all accrued charges since the last billing cadence are compiled into an invoice and sent to the customer.

This separation allows for flexible billing arrangements, such as monthly service measurement with quarterly invoicing, or daily service measurement with weekly billing.

Examples

Customers are only billed for completed service intervals. If a customer is billed while a service interval is still accruing usage, the rate card subscription only includes the usage from the previous service interval. Any new usage is added to the invoice for the next billing cadence.

Monthly service interval and quarterly billing cadence

In this example, a business has the following setup:

• Service interval: Every month
• Billing cadence: Every three months

Stripe calculates charges at the end of each month based on usage. At the end of the third month, the billing cadence ends and Stripe generates an invoice that includes three months of usage.

Service interval of 5 months with an annual billing cadence

In this example, a business has the following setup:

• Service interval: Every 5 months
• Billing cadence: Every year on March 31

The customer is only billed for the completed service intervals within the annual billing cadence. In this example, the invoice is for 10 months of usage, representing the two completed service intervals.

With a 5-month service interval and annual billing candence, the customer is only billed for the completed service intervals.

Lifecycle

Here’s what the lifecycle of a rate card subscription looks like:

1. You create the subscription and reference a rate card.
2. Usage is recorded and aggregated for each service interval.
3. An invoice is created for the subscription according to the billing cadence.
4. The customer’s payment method is charged.

Collection status and servicing status

Rate card subscriptions have two separate states:

• Servicing state: This is tied to the service interval and indicates when to provision or de-provision services. The servicing state of a rate card subscription can be one of:
  • Active
  • Paused
  • Canceled
• Collection state: This is tied to the billing cadence and defines the payment status of the rate card subscription. The collection state can be one of:
  • Current
  • Past due
  • Unpaid

Here’s how the statuses work together for subscriptions that charge a customer’s payment method automatically:

Here’s how the statuses work together for subscriptions that send invoices:

How payments work with rate card subscriptions

When you create a rate card subscription, you define how to collect payments for the usage your customer accrues: charge the customer’s payment method automatically or send them an invoice at the end of each billing cycle. You can collect payment details when you create subscriptions for customers. At the end of the billing cycle, Stripe generates an invoice.

If you charge automatically, Stripe generates an invoice but doesn’t notify your customer about the invoice. If you’ve enabled customer emails, Stripe sends an email receipt for successful payments.

If you send invoices, Stripe generates an invoice and sends it to your customer. which they can pay with the supported payment methods you’ve enabled.

Invoice lifecycle for rate card subscriptions

The basic lifecycle for invoices generated by rate card subscriptions looks like this:

1. The rate card subscription generates a new invoice in draft state.
2. The invoice finalizes immediately. You can’t make changes after the invoice is finalized.
3. The status is set to open and Stripe either automatically attempts to pay it using the customer’s default payment method or sends the customer an invoice.
4. If payment succeeds, the invoice status updates to paid.
5. If payment fails, the invoice remains open and the rate card subscription becomes past_due.

Recovery settings for rate card subscriptions

When payments fail for rate card subscriptions, Stripe’s default recovery behavior helps you recover revenue.

Automated Retries

After creating a rate card subscription, payment failure is the most important event that can occur. Failures occur for many reasons:

• Lack of a payment method on the customer
• Expired payment method
• Declined payment

For rate card subscriptions, Stripe automatically retries failed payments based on your configured subscription settings. You can use either:

• Smart Retries, where machine learning picks the optimal retry time
• Scheduled retries, where you configure the retry policy in the Dashboard

Use the invoice.payment_failed event to monitor subscription payment failure events and retry attempt updates. After a payment attempt on an invoice, its next_payment_attempt value is set using the default retry settings.

If recovery fails after all retry attempts, the rate card subscription transitions to the Unpaid collection state, and the servicing status is set to Paused as shown in the collection status and servicing status tables.

Customer emails

Stripe sends different emails to customers using the email addresses associated with the Customer object:

• A failed payment notification that prompts customers to update their payment information when a payment attempt fails.
• An expiring card notification when a customer’s default payment method card is due to expire.

You can customize the logos and colors your customers see in emails and the Hosted Invoice Payment page by changing the branding settings in the Dashboard.

Rate card subscription events

v2 Events are triggered when subscriptions are activated or canceled. You can listen for events by using Event Destinations.

The following table describes the most common events related to rate card subscriptions. Use the event notifications to build your provisioning logic.

To handle these v2 Events, configure an Event Destination and direct it to your webhook endpoint. You can either:

• Create the Event Destination from Workbench.
• Create the Event Destination through the Stripe API.

See an example of how to set up your webhook endpoint to handle these events.

Rate card subscriptions and tax collection

You can use Stripe Tax to calculate the tax amount on recurring payments for rate card subscriptions. To automatically handle tax calculation when your customer is ready to pay, set the customer’s location details when you create a rate card subscription. Learn more about collecting tax on usage-based rate card subscriptions.