Billing / Stripe connection
Stripe connection
Your customers pay you through your own Stripe account. UsageRail connects to it with a restricted key you create in Stripe. With that key we set up the products and prices for your plans, open Checkout, report usage at the end of each period and keep subscriptions in sync. The money lands in your Stripe balance and is paid out on your usual schedule; UsageRail takes no cut of it.
Each app connects to one Stripe account in one mode. A test app takes a test key and a live app takes a live key, so test customers never end up on live invoices.
Connect
- In the console, open the app's Stripe page.
- In the Stripe Dashboard, create a restricted key with the permissions below. The console lists the same ones, each with what it's for. A test app needs a key starting with
rk_test_, a live app one starting withrk_live_. Secret keys (sk_) are refused, because they can do anything in your account. - Paste the key, confirm that only UsageRail reports usage to this app's meter, and click Connect.
UsageRail first checks every permission. If any are missing, the console names them and nothing is created in your account. Otherwise it creates three things and the app is ready to sell plans and credit packs. Connecting usually takes a few seconds. If Stripe is slow, the console says so; click Connect again and it picks up where it stopped.
Permissions
| Resource | Access | What it's for |
|---|---|---|
| Products | Write | Create a product for each plan you publish |
| Prices | Write | Create each plan version's monthly, yearly and usage prices |
| Customers | Write | Create one Stripe customer per paying customer |
| Checkout Sessions | Write | Open Stripe Checkout when a customer buys a plan |
| Customer portal | Write | Let customers update their card and download invoices |
| Subscriptions | Write | Upgrade, downgrade and cancel subscriptions |
| Subscription Schedules | Write | Schedule downgrades and cancellations for the end of the period |
| Invoices | Write | Hold each period-end invoice open for 72 hours so late usage is billed, and void the invoice of an upgrade the customer drops |
| Refunds | Write | Refund a duplicate subscription if a customer pays twice |
| Billing Meters | Write | Create this app's usage meter and read its totals |
| Meter Events | Write | Report each customer's usage at the end of the period |
| Webhook Endpoints | Write | Get told when a payment, subscription or refund changes |
| Charges | Read | Match refunds to the payments they came from |
| Events | Read | Catch up on anything a webhook missed |
| Tax Settings, Registrations | Read | Add tax at checkout if you use Stripe Tax |
The key can't read your balance or payouts, and UsageRail never sends refunds on its own except for a duplicate subscription.
What UsageRail creates
- A meter named after the app, with the event name
usagerail_followed by the app's ID. Usage goes on invoices through it, so don't send it events from anywhere else: they would be billed, and the period totals would no longer match what UsageRail counted. - A webhook endpoint at
https://api.usagerail.com/stripe/apps/{app ID}/webhook. UsageRail verifies Stripe's signature on each delivery. It listens for checkout, subscription, invoice and refund events. - A customer portal configuration that lets customers update their card and see their invoices. They can't cancel or switch plans there: those go through your developer portal or your own backend, so the change rules stay the same everywhere.
Products, prices and Stripe customers come later, the first time someone buys. Each plan gets a product for its monthly or yearly fee, and a plan that bills overage gets a second one, its name followed by "usage", for the usage price. Each plan version gets its own prices. Cancelling a subscription uses one more product, Subscription ended, with a $0 price that appears on the customer's last invoice.
Invoices at the end of a period
Stripe drafts each subscription's invoice when the period ends and normally finalizes it about an hour later. UsageRail sends a period's usage two hours after it ends, so for subscriptions that bill usage, it moves the draft's finalization to 72 hours after it was created. Usage sent then still makes it onto the invoice, and the period's charge goes out three days after the period ends. Invoices without usage, such as a subscription's first invoice, are left alone.
As a backup, add a grace period in Stripe under Settings, then Billing, then Invoices: 72 hours for invoices that have a metered price. The Stripe page in the console shows each period's result; see usage billing.
Missed webhooks
Every webhook is handled by reading the object it names back from Stripe, so the order events arrive in doesn't matter. If a delivery fails, Stripe retries it, and every 10 minutes UsageRail also reads Stripe's event list since its last check. A subscription change made while our webhook was failing still arrives within minutes.
Stripe Tax
If Stripe Tax is active on your account, Checkout adds tax and saves the customer's address on their Stripe customer. Without it, prices are charged as they are. UsageRail checks the setting each time it opens Checkout, so turning Stripe Tax on applies to the next purchase.
Replacing the key
To rotate the key, create a new one with the same permissions and paste it under Replace the key on the Stripe page. It has to belong to the same Stripe account: UsageRail checks by reading the app's meter with it. To move an app to another Stripe account, create a new app.
There's no disconnect. To stop UsageRail using your account, delete the key in the Stripe Dashboard. Checkout, plan changes and usage reporting then stop working for that app, and existing subscriptions keep charging in Stripe on their own.