Create subscriptions with Stripe Billing

Learn more about Connect

To learn more about Connect, check out the overview. 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 accounts 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.

Restrictions

Using subscriptions with Connect has these restrictions:

• Your platform cant update or cancel a subscription that it didnt create.
• Your platform cant add an application_fee_amount to an invoice that it didnt create, nor to an invoice that contains invoice items the platform didnt 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 arent 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 youre 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:

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

Decide between direct charges and destination charges

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

With direct charges, customers wont be aware of your platforms existence because the authors name, rather than your platforms name, is shown on the statement descriptor. In our online publishing example, readers interact with authors directly.

Direct charges are recommended for connected accounts with access to the full Stripe Dashboard, which includes Standard accounts.

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

curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "customer=
{{CUSTOMER_ID}}" \
  -d "items[0][price]=
{{PRICE_ID}}" \
  -d "expand[0]=latest_invoice.confirmation_secret"

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.confirmation_secret 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.

curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -d "customer=
{{CUSTOMER_ID}}" \
  -d "items[0][price]=
{{PRICE_ID}}" \
  -d "expand[0]=latest_invoice.confirmation_secret" \
  -d "transfer_data[destination]=
{{CONNECTED_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 have created a connected account on the platform. 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 dont subscribe to any particular delivery service or restaurant.

Before you begin

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 isnt 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 doesnt 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:

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 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 cant 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.

Here are the event notifications that subscriptions integrations typically use.

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.