Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
Get started
Collect payments then pay out
Enable other businesses to accept payments directly
Pay out money
Explore Connect
Onboard your accounts
Choose your account type
Standard
Express
Custom
Service agreement types
Payment methods
Account capabilities
Additional verifications
Update verified info
Connect embedded UIs
Quickstart
Get started with Connect embedded UIs
Accept payments
Create a charge
Create a payments page
Create payment links with Connect
Connect integration guide
Automatic payment methods
Set statement descriptors
Connect platforms using the Payment Methods API
Create subscriptions
Create invoices
Debit Express and Custom connected accounts
Pay out
Set bank and debit card payouts
Bank accounts
Manage payout schedule
Manual payouts
Payout reversals
Instant Payouts
Cross-border payouts
Crypto payouts
Manage funds
Add money to your platform balance
Account balance
Handle multiple currencies
Manage accounts
Best practices
Listen for updates
Dashboard account management
Understanding risk offerings
Platform controls for Standard accounts
Make API calls for connected accounts
Set MCCs
Testing
Manage tax forms
Overview
Get started with tax reporting
1099 Tax Support and Communication Guide
Tax form settings
Calculation methods
File tax forms
File tax forms with states
Identify forms with missing information
Update tax forms
Deliver tax forms
E-delivery for 1099 tax forms
Correct tax forms
Split tax forms
Tax year changeover
What's new for tax year 2022
Testing
Connect
·
HomePaymentsMultiparty payments

Create subscriptions with Stripe Billing

With Connect, you can create subscriptions for your customers or connected accounts.

Learn more about Connect

To learn more about Connect, check out the overview. See the create a payments guide to learn more about creating recurring payments on a connected account with subscriptions.

Pricing

We base subscription transactions on Stripe Billing pricing.

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 caseDescription
Create subscriptions from the end customer to the connected accountCreate 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 customersMarketplaces can directly offer membership subscriptions without involving your connected account. In this example, Prices reside on the platform.
Create subscriptions to bill connected accountsPlatforms 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 it didn’t create.
  • 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.
  • Subscriptions aren’t automatically cancelled 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.

Prerequisites

Before you can create subscriptions for your customers or connected accounts, you must:

  1. Create a connected account for each person that receives money on your platform. In our online publishing example, a connected account represents an author.
  2. 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.
  3. Create a customer 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.

Decide between direct charges and destination charges

You can use either direct charges or destination charges to split a customer’s payment between the connected account and your platform.

If you want the connected account to be responsible for Stripe fees, refunds, and chargebacks, use direct charges. With this approach, customers won’t be aware of your platform’s existence because the author’s name, rather than your platform’s name, is shown on the statement descriptor. In our online publishing example, readers interact with authors directly.

Direct charges are also recommended if you’re using a Standard account.

If you want your platform to be responsible for Stripe fees, refunds, and chargebacks, use destination charges. In our online publishing example, customers subscribe to your publishing platform, not directly with specific authors.

Destination charges are also recommended if you’re using Express or 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, make a create subscription call while authenticated as the connected account. Make sure to define the customer and the Price on the connected account.

Expand latest_invoice.payment_intent to include the Payment Element, which is needed 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
curl https://api.stripe.com/v1/subscriptions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -H 'Stripe-Account:
{{CONNECTED_ACCOUNT_ID}}
'
\ -d customer="{{CUSTOMER}}" \ -d "items[0][price]"="{{PRICE}}" \ -d "expand[0]"="latest_invoice.payment_intent"

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.

Expand latest_invoice.payment_intent to include the Payment Element, which you need to confirm the payment. Learn more about Payment Elements.

You can optionally specify an application_fee_percent. Learn more about collecting fees.

Command Line
curl https://api.stripe.com/v1/subscriptions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer="{{CUSTOMER}}" \ -d "items[0][price]"="{{PRICE}}" \ -d "expand[0]"="latest_invoice.payment_intent" \ -d "transfer_data[destination]"="{{CONNECTED_STRIPE_ACCOUNT_ID}}"

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 create the connected account’s token with the platform’s publishable key. The customer must exist within the platform account. When using destination charges, the platform is the merchant of record.

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.

Prerequisites

Before you create subscriptions for your customers, you must:

  1. 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.
  2. 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.

Prerequisites

Before you create subscriptions for your customers or connected accounts, you must:

  1. Create a connected account for each user that receives money on your platform. In this example, the connected account is the gym business.
  2. 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.
  3. Create a customer on the platform with the intended payment method for every 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

If your connected accounts use Stripe to process payments for their end customers, they might have already created a Customer object for each end customer.

To successfully create a subscription for the connected account to pay a recurring fee to the platform, you must create a separate Customer object to represent the connected account.

In the gym example, the gym business uses Stripe to process one-time payments for its gym patrons. They already created a Customer object for each gym patron, but you need to create a different Customer object to represent the gym business itself. Create only one Customer to represent each business entity and don’t create 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. The Customer object involved in the transaction represents the connected account, not the end customer. In our gym example, the CUSTOMER_ID represents the gym business, not the gym patron.

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.

EventDescription
account.application.deauthorizedOccurs when a user disconnects from your account and can be used to trigger required cleanup on your server. Available for Standard accounts.
account.updatedAllows you to monitor changes to connected account requirements and status changes. Available for Standard, Express, and Custom accounts.
person.updatedIf you use the Persons API, allows you to monitor changes to requirements and status changes for individuals. Available for Express and Custom accounts.
payment_intent.succeededOccurs when a payment intent results in a successful charge. Available for all payments, including destination and direct charges
balance.availableOccurs 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).
account.external_account.updatedOccurs when a bank account or debit card attached to a connected account is updated, which can impact payouts. Available for Express and Custom accounts.
payout.failedOccurs when a payout fails. When a payout fails, the external account involved will be disabled, and no automatic or manual payouts can go through until the external account is updated.

Here are the event notifications that subscriptions integrations typically use.

EventDescription
customer.createdSent when a Customer is successfully created.
customer.subscription.createdSent when the subscription is created. The subscription status may be incomplete if customer authentication is required to complete the payment or if you set payment_behavior to default_incomplete. For more details, read about subscription payment behavior.
customer.subscription.deletedSent when a customer’s subscription ends.
customer.subscription.pausedSent when a subscription is fully paused. Invoicing won’t occur until the subscription is resumed.
customer.subscription.resumedSent when a subscription is resumed.
customer.subscription.trial_will_endSent three days before the trial period ends. If the trial is less than three days, this event is triggered.
customer.subscription.updatedSent when the subscription is successfully started, after the payment is confirmed. Also sent whenever a subscription is changed. For example, adding a coupon, applying a discount, adding an invoice item, and changing plans all trigger this event.
invoice.createdSent 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.finalizedSent when an invoice is successfully finalized and ready to be paid.
  • You can send the invoice to the customer. Read more about invoice finalization.
  • Depending on your settings, Stripe automatically charges the default payment method or attempts collection. Read more about emails after finalization.
invoice.finalization_failedThe invoice couldn’t be finalized. Learn how to handle invoice finalization failures by reading the guide. Learn more about invoice finalization in the invoices overview guide.
  • 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 can’t be finalized 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.paidSent 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_requiredSent 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, there are several possible actions to take:

  • Notify the customer. Read about how you can configure subscription settings 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.upcomingSent 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. You can still add extra invoice items, if needed.
invoice.updatedSent 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 a invoice.payment_failed event.
payment_intent.createdSent when a PaymentIntent is created.
payment_intent.succeededSent when a PaymentIntent has successfully completed payment.
  • 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, charge your customer using the on_behalf_of parameter, and monitor subscriptions with webhooks, in addition to other options.

Collect fees on subscriptions

Use coupons

Use trial periods

Set up the customer portal

Monitor subscriptions with webhooks

Make the connected account the settlement merchant using on_behalf_of

Understand disconnect behavior

See also

  • Best practices for going live with Connect
  • Creating invoices
  • Creating charges
  • Share customers across accounts
  • Multiple currencies
Was this page helpful?
Questions? Contact us.
Watch our developer tutorials.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Use cases
Create subscriptions from the end customer to the connected account
Create subscriptions to bill platform end customers
Create subscriptions to bill connected accounts
Enable your integration to receive event notifications
Test your integration
Additional options
See also
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to Stripe docs and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$