Existing subscriptions from Stripe

If you already sell your API through Stripe, your customers don't have to subscribe again. Map the prices they're on to UsageRail plans. UsageRail then applies each plan's rate limits and quota to those customers and, for a usage-based price, sends their usage to Stripe at the end of every billing period. What they pay stays exactly as it is in Stripe, and you keep changing and cancelling these subscriptions there.

Before you start

• Connect Stripe for the app.
• Create a plan for each kind of subscription you have, with the limits those customers should get. You can hide it from your pricing page. Its price only matters to people who buy it through UsageRail: customers on an existing subscription pay what their Stripe price says. Prepaid plans can't be used, since they have no subscription.

Choose the meter

This step is only for usage-based prices. On the app's Stripe page, open Existing subscriptions and pick the meter your usage prices are on. UsageRail accepts a meter that:

• receives raw events, with no pre-aggregation window;
• adds up event values;
• reads the customer from stripe_customer_id and the amount from value, which are Stripe's defaults.

An app uses one existing meter, and two UsageRail apps can't share one. Once a usage price on the meter is mapped, the meter can't be changed, and after you remove it, not until its last periods have been sent and checked. You also confirm that only UsageRail will send events to it; when to stop sending your own is below.

Map your prices

Add the Stripe price ID for each monthly or yearly fee and each usage price, then choose the UsageRail plan to map it to. A price can be mapped if:

• it's billed every month or every year, and a usage price every month (UsageRail keeps per-minute usage for 45 days, so it can't add up a yearly period);
• it's in the same currency as your plans;
• for a usage price, it's on the chosen meter and bills each unit or in tiers. Package pricing (Stripe's transform quantity) isn't supported.

Within a couple of minutes, UsageRail finds the subscriptions already on the price. Subscriptions you create on it in Stripe later are picked up as they're created.

A subscription's plan comes from its mapped fee price, or from its usage price when the fee isn't mapped. These customers always get the plan's current version: when you change the plan's limits, they get the new ones right away. Their price can't change with it, because it lives in Stripe.

Link customers to Stripe customers

UsageRail links your customers to Stripe customers. It checks these sources in order and uses the first link it finds:

1. Your SDK. If you use your own auth, return the Stripe customer ID along with the customer's ID:

   jsCopy

   app.use(usageRail({
     appKey: process.env.USAGERAIL_APP_KEY,
     auth: "custom",
     consumer: (req) => (req.user ? { id: req.user.accountId, stripeCustomerId: req.user.stripeCustomerId } : null),
   }));

   In Python, return {"id": ..., "stripe_customer_id": ...} from consumer.

2. The console. On a customer's page, choose Link a Stripe customer and enter the ID.

3. Stripe metadata. On the Existing subscriptions page, set a metadata key such as user_id. When a Stripe customer's value for that key is a customer's UsageRail ID or external ID, they're linked. If your app hashes external IDs, the value is hashed the same way before it's compared. When you edit the metadata in Stripe, the link follows within a few minutes.

Several customers can share one Stripe customer, a team for example. Their usage is added up and sent as one total, and they're always billed for overage: they can't be stopped at a limit or use prepaid credits.

Until a Stripe customer is linked to someone, nobody gets a plan from that subscription and its usage isn't sent. The Existing subscriptions page lists those Stripe customers.

When UsageRail starts reporting

UsageRail reports a subscription's usage from its first billing period that starts after you map the usage price. The period under way when you map it is marked as started before import and isn't reported: keep sending usage for that period the way you do now, and stop when it ends. For a subscription that starts after you mapped the price, UsageRail reports from its first period, so don't send usage for it yourself.

Usage billing

Two hours after a period ends, UsageRail adds up the usage of every customer linked to the Stripe customer and sends one meter event. After that it runs the same checks as for plans sold through UsageRail: that Stripe recorded the same total, and that the finalized invoice bills the same quantity and amount. The expected amount comes from your Stripe price and its tiers. Invoices for these periods are also held open for 72 hours, so the charge goes out about three days after the period ends.

A period isn't sent, and shows on the Stripe page, when:

• Needs setup: no customer is linked to the Stripe customer, or the Stripe customer has more than one subscription item on the meter during the period. Stripe would bill the usage on each item, so end the extra one.
• Customer changed: during the period, your SDK sent a different Stripe customer for one of the linked customers. Check their links, then choose Send with current links.

UsageRail checks these again every 30 minutes and sends the period once they're fixed, as long as the invoice is still a draft. If Stripe finalizes it first, the period is marked not billed.

If one of the linked customers also subscribed to a plan through UsageRail, that subscription comes first. Their usage in its periods goes on its invoice and isn't added to the existing subscription's total.

Changing and cancelling

Change and cancel these subscriptions in Stripe, as you do now. UsageRail reads the result within minutes. Customers on an existing subscription can't subscribe, switch plans or cancel in the portal, and the server API and console answer 409 subscription_managed_in_stripe for them.

If you change a subscription's price in the middle of a period, Stripe doesn't bill usage reported after the period for it, so that period is marked not billed.

Removing a price

Removing a mapped price stops treating its subscriptions as existing subscriptions. Their customers move back to your default plan, unless another price on the same subscription is still mapped. Usage for the period under way isn't sent; a period that has already ended is still sent.

Deleting a customer doesn't cancel their existing subscription, since it's yours in Stripe; deletion waits until their last period's usage has been sent. Deleting the app stops reporting: periods that have ended are sent, the one under way isn't. See deleting.