Create subscriptions with Stripe Billing
With Connect, you can create subscriptions for your customers or connected accounts.
Software as a Service (SaaS) and marketplace businesses use Stripe Connect to route payments between themselves, customers, and connected accounts. You can use Connect to route payments or payouts and use Stripe Billing to support your recurring revenue model.
Use cases
You can create subscriptions for connect accounts, which supports several approaches for collecting payments. You can create subscriptions for your connected account’s customers using direct or destination charges, for your end customers to directly transact with your platform, and to charge your connected accounts a fee for using your platform.
The following use cases describe how to use Stripe Billing to create subscriptions from end customers to connected accounts, to bill platform end customers, and to bill connected accounts.
| Use case | Description |
|---|---|
| Create subscriptions from the end customer to the connected account | Create subscriptions for end customers to your connected accounts, which supports several approaches for collecting payments. In this example, Prices reside on the connected account. |
| Create subscriptions to bill platform end customers | Marketplaces can directly offer membership subscriptions without involving your connected account. In this example, Prices reside on the platform. |
| Create subscriptions to bill connected accounts | Platforms can create subscriptions for their connected accounts. In this example, Prices reside on the platform. |
Restrictions
Using subscriptions with Connect has these restrictions:
- Your platform can’t update or cancel a subscription that another platform created.
- Your platform can’t add an application _ fee _ amount to an invoice that it didn’t create, nor to an invoice that contains invoice items the platform didn’t create.
- Only connected accounts with access to the full Stripe Dashboard can manage their customers’ subscriptions. For other connected accounts, the platform must manage their customers’ subscriptions.
- Subscriptions aren’t automatically canceled when you disconnect from the platform. You must cancel the subscription after disconnection. You can use webhooks to monitor connected account activity .
Create subscriptions from the end customer to the connected account
If you’re building a platform, you can create subscriptions for your connected accounts’ customers, optionally taking a per-payment fee for your platform.
This example builds an online publishing platform that allows customers to subscribe to their favorite authors and pay them a monthly fee to receive premium blog posts from each author.
Before you begin
Before you can create subscriptions for your customers or connected accounts, you must:
- Create a connected account for each person that receives money on your platform. Follow the SaaS account setup for direct charges or the marketplace account setup for destination charges. In our online publishing example, a connected account represents an author.
- Create a pricing model. For this example, we create a flat-rate pricing model to charge customers a fee on a recurring basis, but per-seat and usage-based pricing are also supported.
- Create a customer with the intended payment method for each person that subscribes to a connected account. In our online publishing example, you create a customer for each reader that subscribes to an author.
Choose a charge and settlement model
You can use direct charges or destination charges to split a customer’s payment between the connected account and your platform. Before creating a subscription, choose where to create charges and which account is the merchant of record. The merchant of record determines whose statement descriptor and business details apply to the payment.
| Model | Charge created on | merchant of record | Choose when |
|---|---|---|---|
| Direct charge | Connected account | Connected account | Customers transact directly with the connected account and see its statement descriptor. |
Destination charge without on_behalf_of | Platform | Platform | Customers transact with your platform and see your statement descriptor. |
| Destination charge with on_behalf_of | Platform | Connected account | Customers transact with the connected account through your platform and see the connected account’s statement descriptor and applicable business details. |
In our online publishing example, direct charges mean that readers interact with authors directly and see the author’s name, rather than your platform’s name, on the statement descriptor. Refunds and chargebacks debit the connected account’s balance. Responsibility for fees and negative balances depends on your account configuration.
Direct charges are recommended for connected accounts with access to the full Stripe Dashboard, which includes Standard accounts.
In the same online publishing example using destination charges, Stripe charges your platform balance for fees, refunds, and chargebacks, whether or not you set on_behalf_of. Set on_behalf_of to designate the author or platform as merchant of record.
Destination charges are recommended for connected accounts with access to the Express Dashboard or connected accounts without access to a Stripe-hosted dashboard, which includes Express and Custom accounts.
For more information about the different types of Connect charges, see Charge types.
Use direct charges to create a subscription
To create a subscription with Charges associated to the connected account, create a subscription while authenticated as the connected account. Make sure to define the customer with a default payment method and the Price on the connected account. To use a customer without a default payment method, set payment_behavior: "default_incomplete". Learn more about payment behavior.
Expand latest_invoice.confirmation_secret to include the Payment Element, which you need to confirm the payment. Learn more about Payment Elements.
For an end-to-end example of how to implement a subscription signup and payment flow in your application, see the subscriptions integration guide.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Optionally, you can specify a percentage of the invoice amount to collect as an application fee.
Use destination charges to create a subscription
To create a subscription with Charges associated to the platform and automatically create transfers to a connected account, make a create subscription call while providing the connected account ID as the transfer_data[destination] value.
For an Accounts v2 connected account, destination charges require the recipient configuration with an active stripe_balance.stripe_transfers capability.
Expand latest_invoice.confirmation_secret to include the Payment Element, which you need to confirm the payment. Learn more about Payment Elements.
Optionally, you can specify a percentage of the invoice amount to collect as an application fee.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Make the connected account the merchant of record with on_behalf_of
Set on_behalf_of to the connected account ID when creating or updating a subscription to make that account the merchant of record. For destination charges, omitting on_behalf_of makes your platform the merchant of record.
When you set on_behalf_of:
- Charges settle in the connected account’s country and settlement currency, using the fee structure for that country.
- The connected account’s statement descriptor appears on the customer’s credit card statement. If the connected account is in a different country than your platform, its address and phone number also appear.
- The connected account’s payout delay settings determine how long it takes for the charge funds to become available for payout.
- Hosted resources, including email receipts, invoices, and the customer portal, can use the connected account’s branding.
The connected account must have a payments capability such as card_payments. If the connected account uses Accounts v2, it must also have the merchant configuration; otherwise, payments fail. For destination charges or separate charges and transfers, the Accounts v2 connected account also needs the recipient configuration with an active stripe_balance.stripe_transfers capability. Accounts under the recipient service agreement can’t request payments capabilities and can’t use on_behalf_of.
For more details, see Charge on behalf of a connected account, separate charges and transfers, and the connected account’s branding settings.
Configure Stripe Tax liability and the invoice issuer separately with automatic_tax[liability] and invoice_settings[issuer]. See Stripe Tax with Connect to determine tax liability and configure Billing for connected-account tax liability.
Create a destination charge with on_behalf_of
Create the subscription on the platform with both on_behalf_of and transfer_data[destination] set to the connected account ID. This example also includes an optional application_fee_percent:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Create separate charges and transfers with on_behalf_of
For separate charges and transfers, create the subscription on the platform with on_behalf_of, without a Stripe-Account header. This example doesn’t transfer funds automatically. Create transfers separately to send funds to the connected account.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Additional steps before you create a subscription
To create a destination charge, define both the customer and the price on the platform account. You must have created a connected account on the platform. The customer must exist within the platform account. Your platform is the merchant of record unless you set on_behalf_of to the connected account ID.
Create subscriptions to bill platform end customers
You can use Stripe Billing to create subscriptions for your end customers to directly transact with your platform without involving your connected accounts.
This example builds a marketplace that allows customers to order on-demand delivery from restaurants. This marketplace offers customers a premium monthly subscription that waives their delivery fees. Customers who subscribe to the premium offering pay the marketplace directly and don’t subscribe to any particular delivery service or restaurant.
Before you begin
Before you create subscriptions for your customers, you must:
- Create a pricing model. For this example, we create a flat-rate pricing model to charge customers a fee on a recurring basis, but per-seat and usage-based pricing are also supported.
- Create a customer record for every customer you want to bill.
You can also create a connected account for each user that receives money from your marketplace. In our on-demand restaurant delivery example, a connected account is a restaurant or a delivery service. However, this step isn’t required for customers to subscribe to your marketplace directly.
Create a subscription
To create a subscription where your platform receives the funds, without any money going to connected accounts, follow the Subscriptions guide to create a subscription with Stripe Billing.
Create separate charges and transfers
If you want to manually transfer a portion of the funds that your platform receives to your connected accounts later, use separate charges and transfers to pay out funds to one or more connected accounts. In our on-demand restaurant delivery example, you can use separate charges and transfers to pay out an affiliate fee to a delivery driver or restaurant who refers a customer to subscribe to the premium delivery service.
Create subscriptions to bill connected accounts
You can use Stripe Billing to create subscriptions to charge your connected accounts a fee for using your platform.
This example builds a gym management software platform that allows gym businesses to pay a monthly fee to use the software to manage scheduling and appointments for classes. The gym businesses pay the subscription fee, not the gym patrons.
The gym management software also facilitates one-time payments between the gym patron and gym business for each class that the gym patron enrolls in. The monthly subscription is between the connected account and the platform, which doesn’t involve the gym patron in the transaction.
In the diagram above, the gym business is the connected account and the gym patron is the end customer.
Before you begin
Before you create subscriptions for your connected accounts, you must:
- Create a pricing model. For this example, we create a flat-rate pricing model to charge customers a fee on a recurring basis, but per-seat and usage-based pricing are also supported.
- Create a customer on the platform with the intended payment method for each connected account you want to bill. In the gym management software example, you create a customer for each gym business:
Create a Customer object to represent the connected account
To create a subscription for the connected account to pay a recurring fee to the platform, you must create a Customer object to represent the connected account. The Account object allows the connected account to collect payments from its customers, but the platform can’t use it to collect recurring payments from the connected account. Create only one Customer to represent each business entity instead of creating a Customer to represent each owner, manager, or operator of the business.
Create a subscription for the connected account
To create a subscription where your platform receives the funds from your connected accounts, follow the Subscriptions guide to create a subscription with Stripe Billing. Pass the Customer object representing the connected account in the customer parameter.
Enable your integration to receive event notifications
Stripe creates event notifications when changes happen in your account, like when a recurring payment succeeds or when a payout fails. To receive these notifications and use them to automate your integration, set up a webhook endpoint. For example, you could provision access to your service when you receive the invoice.paid event.
Event notifications for Connect and subscriptions integrations
Here are the event notifications that Connect integrations typically use.
| Event | data.object type | Description |
|---|---|---|
account.application.deauthorized | application | Occurs when a connected account disconnects from your platform. You can use it to trigger cleanup on your server. Available for connected accounts with access to the Stripe Dashboard, which includes Standard accounts. |
account.external_account.updated | An external account, such as card or bank_account | Occurs when a bank account or debit card attached to a connected account is updated, which can impact payouts. Available for connected accounts that your platform controls, which includes Custom and Express accounts, and Standard accounts with platform controls enabled. |
account.updated | account | Allows you to monitor changes to connected account requirements and status changes. Available for all connected accounts. |
balance.available | balance | Occurs when your Stripe balance has been updated. For example, when funds you’ve added from your bank account are available for transfer to your connected account. |
payment_intent.succeeded | payment_intent | Occurs when a payment intent results in a successful charge. Available for all payments, including destination and direct charges. |
payout.failed | payout | Occurs when a payout fails. When a payout fails, the external account involved is disabled, and no automatic or manual payouts can be processed until the external account is updated. |
person.updated | person | Occurs when a Person associated with the Account is updated. If you use the Persons API to handle requirements, listen for this event to monitor changes to requirements and status changes for individuals. Available for connected accounts that your platform controls, which includes Custom and Express accounts, and Standard accounts with platform controls enabled. |
Here are the event notifications that subscriptions integrations typically use.
Public preview
The Accounts v2 API is in GA for Connect users, and in public preview for other Stripe users.
Regardless of whether you use Accounts v2 objects or Customer objects to represent your customers, use the customer.subscription events to track subscription events.
v2.core.account.created | Sent when a v2 Account is successfully created. |
customer.created | Sent when a Customer is successfully created. |
customer.subscription.created | Sent when the subscription is created. The subscription status might be incomplete if customer authentication is required to complete the payment or if you set payment_behavior to default_incomplete. |
customer.subscription.deleted | Sent when a customer’s subscription ends. |
customer.subscription.paused | Sent when a subscription’s status changes to paused. For example, we send this when you configure a subscription to pause when a free trial ends without a payment method. Invoicing won’t occur until the subscription resumes. We don’t send this event if you pause payment collection because invoices continue to be created during that time period. |
customer.subscription.resumed | Sent when you resume a subscription previously in a paused status. This doesn’t apply when you unpause payment collection. |
customer.subscription.trial_will_end | Sent 3 days before the trial period ends. If the trial is less than 3 days, this event is triggered. |
customer.subscription.updated | Sent when a subscription starts or changes. For example, renewing a subscription, adding a coupon, applying a discount, adding an invoice item, and changing plans all trigger this event. |
entitlements.active_entitlement_summary.updated | Sent when a customer’s active entitlements are updated. When you receive this event, you can provision or de-provision access to your product’s features. Read more about integrating with entitlements. |
invoice.created | Sent when an invoice is created for a new or renewing subscription. If Stripe fails to receive a successful response to invoice.created, then finalizing all invoices with automatic collection is delayed for up to 72 hours. Read more about finalizing invoices. Respond to the notification by sending a request to the Finalize an invoice API. |
invoice.finalized | Sent when an invoice is successfully finalized and ready to be paid. You can send the invoice to the customer. View invoice finalization to learn more. Depending on your settings, we automatically charge the default payment method or attempt collection. View emails after finalization to learn more. |
invoice.finalization_failed | The invoice failed to finalize. Learn more about how to handle invoice finalization failures and invoice finalization. Inspect the invoice’s last_finalization_error to determine the cause of the error. If you’re using Stripe Tax, check the Invoice object’s automatic_tax field. If automatic_tax[status]=requires_location_inputs, the invoice fails to finalize and payments can’t be collected. Notify your customer, and collect the required customer location. If automatic_tax[status]=failed, retry the request later. |
invoice.paid | Sent when the invoice is successfully paid. You can provision access to your product when you receive this event and the subscription status is active. |
invoice.payment_action_required | Sent when the invoice requires customer authentication. Learn how to handle the subscription when the invoice requires action. |
invoice.payment_failed | A payment for an invoice failed. The PaymentIntent status changes to requires_action. The status of the subscription continues to be incomplete only for the subscription’s first invoice. If a payment fails, you can take several possible actions: Notify the customer. Configure your subscription settings in the Dashboard to enable Smart Retries and other revenue recovery features. If you’re using PaymentIntents, collect new payment information and confirm the PaymentIntent. Update the default payment method on the subscription. |
invoice.upcoming | Sent a few days prior to the renewal of the subscription. The number of days is based on the number set for Upcoming renewal events in the Dashboard. For existing subscriptions, changing the number of days takes effect on the next billing period. You can still add extra invoice items, if needed. |
invoice.updated | Sent when a payment succeeds or fails. If payment is successful the paid attribute is set to true and the status is paid. If payment fails, paid is set to false and the status remains open. Payment failures also trigger an invoice.payment_failed event. |
payment_intent.created | Sent when a PaymentIntent is created. |
payment_intent.succeeded | Sent when a PaymentIntent has successfully completed payment. |
subscription_schedule.aborted | Sent when a subscription schedule is canceled because payment delinquency terminated the related subscription. |
subscription_schedule.canceled | Sent when a subscription schedule is canceled, which also cancels any active associated subscription. |
subscription_schedule.completed | Sent when all phases of a subscription schedule complete. |
subscription_schedule.created | Sent when a new subscription schedule is created. |
subscription_schedule.expiring | Sent 7 days before a subscription schedule is set to expire. |
subscription_schedule.released | Sent when a subscription schedule is released, or stopped and disassociated from the subscription, which remains. |
subscription_schedule.updated | Sent when a subscription schedule is updated. |
- Create a webhook endpoint
- Listen to events with the Stripe CLI
- Connect webhooks
- Subscription webhooks
Test your integration
After you create your subscription, thoroughly test your integration before you expose it to customers or use it for any live activity. Learn more about testing Stripe Billing.
Additional options
After you create your subscription, you can specify an application_fee_percent, set up the customer portal, and monitor subscriptions with webhooks, in addition to other options.