# Create subscriptions with Stripe Billing With Connect, you can create subscriptions for your customers or connected accounts. To learn more about *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients), check out the [overview](https://docs.stripe.com/connect.md). We base *subscription* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis) transactions on [Stripe Billing pricing](https://stripe.com/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* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit) and use Stripe Billing to support your recurring revenue model. ## Use cases You can create [subscriptions](https://docs.stripe.com/billing/subscriptions/overview.md) 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. (See full diagram at https://docs.stripe.com/connect/subscriptions) 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](https://docs.stripe.com/connect/subscriptions.md#customer-connected-account) | Create subscriptions for end customers to your connected accounts, which supports several approaches for collecting payments. In this example, [Prices](https://docs.stripe.com/api/prices.md) reside on the connected account. | | [Create subscriptions to bill platform end customers](https://docs.stripe.com/connect/subscriptions.md#customer-platform) | Marketplaces can directly offer membership subscriptions without involving your connected account. In this example, [Prices](https://docs.stripe.com/api/prices.md) reside on the platform. | | [Create subscriptions to bill connected accounts](https://docs.stripe.com/connect/subscriptions.md#connected-account-platform) | Platforms can create subscriptions for their connected accounts. In this example, [Prices](https://docs.stripe.com/api/prices.md) 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. - 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](https://docs.stripe.com/connect/webhooks.md). ## 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. (See full diagram at https://docs.stripe.com/connect/subscriptions) 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](https://docs.stripe.com/connect/accounts.md) for each person that receives money on your platform. In our online publishing example, a connected account represents an author. 1. Create a pricing model. For this example, we create a flat-rate [pricing model](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) to charge customers a fee on a recurring basis, but per-seat and usage-based pricing are also supported. 1. Create a [customer with the intended payment method](https://docs.stripe.com/billing/customer.md#manage-customers) 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. With direct charges, 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 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](https://docs.stripe.com/connect/charges.md#types). ### Use direct charges to create a subscription To create a subscription with [Charges](https://docs.stripe.com/api/charges/object.md) associated to the connected account, [create a subscription](https://docs.stripe.com/api.md#create_subscription) while [authenticated as the connected account](https://docs.stripe.com/connect/authentication.md#stripe-account-header). Make sure to define the customer with a default payment method and the [Price](https://docs.stripe.com/api/prices.md) on the connected account. To use a customer without a default payment method, set `payment_behavior: "default_incomplete"`. Learn more about [payment behavior](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior). Expand `latest_invoice.confirmation_secret` to include the Payment Element, which you need to confirm the payment. Learn more about [Payment Elements](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md?payment-ui=elements&api-integration=paymentintents#add-the-payment-element-to-your-page). For an end-to-end example of how to implement a subscription signup and payment flow in your application, see the [subscriptions integration](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md) guide. ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_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](https://docs.stripe.com/api/charges/object.md) associated to the platform and automatically create transfers to a connected account, make a [create subscription](https://docs.stripe.com/api.md#create_subscription) call while providing the connected account ID as the `transfer_data[destination]` [value](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-transfer_data). Expand `latest_invoice.confirmation_secret` to include the Payment Element, which you need to confirm the payment. Learn more about [Payment Elements](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md?payment-ui=elements&api-integration=paymentintents#add-the-payment-element-to-your-page). You can optionally specify an [application_fee_percent](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-application_fee_percent). Learn more about [collecting fees](https://docs.stripe.com/connect/subscriptions.md#collect-fees). ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d "items[0][price]"="{{PRICE_ID}}" \ -d "expand[0]"="latest_invoice.confirmation_secret" \ -d "transfer_data[destination]"="{{CONNECTEDACCOUNT_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* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account). ## 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. (See full diagram at https://docs.stripe.com/connect/subscriptions) 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: 1. Create a pricing model. For this example, we create a flat-rate [pricing model](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) to charge customers a fee on a recurring basis, but per-seat and usage-based pricing are also supported. 1. Create a [customer](https://docs.stripe.com/billing/customer.md#manage-customers) record for every customer you want to bill. You can also create a [connected account](https://docs.stripe.com/connect/accounts.md) 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](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md) 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](https://docs.stripe.com/connect/separate-charges-and-transfers.md) 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. (See full diagram at https://docs.stripe.com/connect/subscriptions) 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: 1. Create a pricing model. For this example, we create a flat-rate [pricing model](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) to charge customers a fee on a recurring basis, but per-seat and usage-based pricing are also supported. 1. 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](https://docs.stripe.com/api/customers/create.md) 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](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md) 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/connect/standard-accounts.md). | | `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](https://docs.stripe.com/connect/payouts-bank-accounts.md), which can impact payouts. Available for connected accounts that your platform controls, which includes Custom and Express accounts, and Standard accounts with [platform controls](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts.md) 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](https://docs.stripe.com/connect/top-ups.md) 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](https://docs.stripe.com/connect/destination-charges.md) and [direct](https://docs.stripe.com/connect/direct-charges.md) charges. | | `payout.failed` | `payout` | Occurs when [a payout fails](https://docs.stripe.com/connect/payouts-connected-accounts.md#webhooks). 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](https://docs.stripe.com/connect/handling-api-verification.md#verification-process), 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](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts.md) enabled. | Here are the event notifications that subscriptions integrations typically use. | Event | Description | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.created` | Sent when a [Customer](https://docs.stripe.com/api/customers/object.md) 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](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior). | | `customer.subscription.deleted` | Sent when a customer’s subscription ends. | | `customer.subscription.paused` | Sent when a subscription’s `status` changes to `paused`. For example, this is sent when a subscription is [configured](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_settings-end_behavior-missing_payment_method) to pause when a [free trial ends without a payment method](https://docs.stripe.com/billing/subscriptions/trials.md#create-free-trials-without-payment). Invoicing won’t occur until the subscription is [resumed](https://docs.stripe.com/api/subscriptions/resume.md). We don’t send this event if [payment collection is paused](https://docs.stripe.com/billing/subscriptions/pause-payment.md) because invoices continue to be created during that time period. | | `customer.subscription.resumed` | Sent when a subscription previously in a `paused` status is resumed. This doesn’t apply when [payment collection is unpaused](https://docs.stripe.com/billing/subscriptions/pause-payment.md#unpausing). | | `customer.subscription.trial_will_end` | Sent three days before the [trial period ends](https://docs.stripe.com/billing/subscriptions/trials.md). If the trial is less than three days, this event is triggered. | | `customer.subscription.updated` | Sent when a subscription starts or [changes](https://docs.stripe.com/billing/subscriptions/change.md). 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](https://docs.stripe.com/billing/entitlements.md). | | `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](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md) is delayed for up to 72 hours. Read more about [finalizing invoices](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized). - Respond to the notification by sending a request to the [Finalize an invoice](https://docs.stripe.com/api/invoices/finalize.md) 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](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized) to learn more. - Depending on your settings, we automatically charge the default payment method or attempt collection. View [emails after finalization](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#emails) to learn more. | | `invoice.finalization_failed` | The invoice couldn’t be finalized. Learn how to [handle invoice finalization failures](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures) by reading the guide. Learn more about [invoice finalization](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized) in the invoices overview guide. - Inspect the Invoice’s [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) to determine the cause of the error. - If you’re using Stripe Tax, check the Invoice object’s [automatic_tax](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) 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](https://docs.stripe.com/tax/customer-locations.md). - 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](https://docs.stripe.com/billing/subscriptions/overview.md#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. - Configure your [subscription settings](https://dashboard.stripe.com/settings/billing/automatic) in the Dashboard to enable [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) and other revenue recovery features. - If you’re using PaymentIntents, collect new payment information and [confirm the PaymentIntent](https://docs.stripe.com/api/payment_intents/confirm.md). - Update the [default payment method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-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](https://dashboard.stripe.com/settings/billing/automatic). For existing subscriptions, changing the number of days takes effect on the next billing period. You can still add [extra invoice items](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-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 a `invoice.payment_failed` event. | | `payment_intent.created` | Sent when a [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) 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](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#subscription-schedule-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](https://docs.stripe.com/api/subscription_schedules/release.md), or stopped and disassociated from the subscription, which remains. | | `subscription_schedule.updated` | Sent when a subscription schedule is updated. | - [Create a webhook endpoint](https://docs.stripe.com/webhooks.md#webhook-endpoint-def) - [Listen to events with the Stripe CLI](https://docs.stripe.com/webhooks.md#local-listener) - [Connect webhooks](https://docs.stripe.com/connect/webhooks.md) - [Subscription webhooks](https://docs.stripe.com/billing/subscriptions/webhooks.md) ## 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](https://docs.stripe.com/billing/testing.md). ## Additional options After you create your subscription, you can specify an [application_fee_percent](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-application_fee_percent), set up the *customer portal* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details), charge your customer using the `on_behalf_of` parameter, and monitor subscriptions with webhooks, in addition to other options. ### Collect fees on subscriptions One time each billing period, Stripe takes this percentage of the final invoice amount, including any bundled invoice items, discounts, or account balance adjustments, as a fee for the platform. We make this deduction before charging any Stripe fees. When creating or updating a subscription, you can optionally specify an [application_fee_percent](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-application_fee_percent). This must be a non-negative decimal between 0 and 100, with at most two decimal places. This example shows `application_fee_percent` for subscriptions that use direct charges on connected accounts: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d customer="{{CUSTOMER_ID}}" \ -d "items[0][price]"="{{PRICE_ID}}" \ -d "expand[0]"="latest_invoice.confirmation_secret" \ -d application_fee_percent=10 ``` This example shows `application_fee_percent` for subscriptions that use destination charges: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d "items[0][price]"="{{PRICE_ID}}" \ -d "expand[0]"="latest_invoice.confirmation_secret" \ -d application_fee_percent=10 \ -d "transfer_data[destination]"="{{CONNECTEDACCOUNT_ID}}" ``` ### Calculating application fee percent To see how we calculate `application_fee_percent`, consider this scenario: - A subscription costs 30 USD per billing cycle - There’s a 10 USD invoice that’s on the next invoice - A 50% coupon applies - The `application_fee_percent` is 10 In this case, the total application fee is 2 USD: (30 USD + 10 USD) * 50% * 10%. ### Percent fees and flat fees Application fees on subscriptions must normally be a percentage because the amount billed with subscriptions often varies. You can’t set a subscription’s recurring application fee as a flat amount. However, you can charge a flat `application_fee_amount` on an invoice, as explained in the [next section](https://docs.stripe.com/connect/subscriptions.md#subscription-invoices). The `application_fee_percent` parameter doesn’t apply to invoices you create outside of a subscription billing period. For example, it doesn’t apply to proration invoice items that are immediately invoiced. In these cases, directly set an `application_fee_amount` on the invoice for the amount you want to charge. ### Work with invoices created by subscriptions Each cycle, subscriptions create invoices and invoices create charges. For more information about subscription cycles, see the [subscription lifecycle](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle). To charge a flat or dynamic fee that can’t be automatically calculated with `application_fee_percent`, add an `application_fee_amount` directly on each invoice created by the subscription. This example shows an `application_fee_amount` for an invoice with a direct charge on the connected account: #### curl ```bash curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \ -u <>: \ -d application_fee_amount=100 \ -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" ``` This example shows an `application_fee_amount` for an invoice with a destination charge: #### curl ```bash curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \ -u <>: \ -d application_fee_amount=100 \ -d "transfer_data[destination]"="{{CONNECTED_STRIPE_ACCOUNT_ID}}" ``` To automatically charge an `application_fee_amount`, create a *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) that listens for the `invoice.created` event. You can also do this manually by creating an invoice for pending invoice items and setting an application fee on it. The `application_fee_amount` set directly on an invoice overrides any application fee amount calculated with `application_fee_percent` and is capped at the invoice’s final charge amount. ### Use coupons After creating subscriptions, you can add coupons to your subscriptions. [Coupons](https://docs.stripe.com/api/coupons.md) are merchant-facing objects you can use to control discounts on [subscriptions](https://docs.stripe.com/billing/subscriptions/overview.md) or [invoices](https://docs.stripe.com/api/invoices.md). [Promotion codes](https://docs.stripe.com/api/promotion_codes.md) are customer-facing codes that are created on top of coupons and can be shared directly with your customers. Learn how to [create customer-facing codes](https://docs.stripe.com/billing/subscriptions/coupons.md#promotion-codes). ### Use trial periods You can start a customer’s [subscription](https://docs.stripe.com/billing/subscriptions/overview.md) with a free trial period by providing a `trial_end` argument when [creating the subscription](https://docs.stripe.com/api.md#create_subscription): ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d customer="{{CUSTOMER_ID}}" \ -d "items[0][price]"="{{PRICE_ID}}" \ -d trial_end=1610403705 ``` The `trial_end` parameter takes a timestamp indicating the exact moment the trial ends. When creating a subscription, you can alternatively use the [trial_period_days](https://docs.stripe.com/api.md#create_subscription-trial_period_days) argument: an integer representing the number of days the trial lasts, from the current moment. When creating a subscription with a trial period, we don’t require a payment method for the customer. We still create an immediate [invoice](https://docs.stripe.com/api/invoices.md), but for 0 USD. Three days before the trial period is up, a `customer.subscription.trial_will_end` event is sent to your [webhook endpoint](https://docs.stripe.com/billing/subscriptions/webhooks.md). After seeing that notification, take any necessary actions, such as informing the customer that billing is about to begin. When the trial ends, a new billing cycle starts for the customer. After the trial period is up, Stripe generates an invoice and sends an `invoice.created` event notification. Approximately 1 hour later, Stripe attempts to charge that invoice. To end a trial early, make an [update subscription](https://docs.stripe.com/api.md#update_subscription) API call, setting the `trial_end` value to a new timestamp, or **now** to end immediately: ```curl curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -u "<>:" \ -d trial_end=now ``` Learn more about how to [delay payments on active subscriptions using trial periods](https://docs.stripe.com/billing/subscriptions/trials.md). ### Set up the customer portal The customer portal allows your customers to manage [subscriptions](https://docs.stripe.com/billing/subscriptions/overview.md) and [invoices](https://docs.stripe.com/api/invoices.md). If you’re a Billing user, the portal lets your customers manage their subscriptions (update, cancel, pause, and so on). Invoicing-only users can use the portal to pay an invoice, add a payment method, and so on. Learn more how to [integrate the customer portal](https://docs.stripe.com/customer-management.md). ### Monitor subscriptions with webhooks We send notifications to your app using [webhooks](https://docs.stripe.com/webhooks.md). Webhooks are especially important for [subscriptions](https://docs.stripe.com/billing/subscriptions/overview.md), where most activity occurs asynchronously. To use webhooks with your subscriptions: 1. Create a webhook endpoint in your app. 1. Add logic to handle Stripe events. For subscriptions, these include payment failures and subscription state changes (like moving from trial to an active state). 1. Test your webhook endpoint to confirm that it’s working as expected. Learn to use webhooks to [receive notifications of subscription activity](https://docs.stripe.com/billing/subscriptions/webhooks.md). ### Make the connected account the settlement merchant using on_behalf_of You can create or update a subscription with the `on_behalf_of` parameter for a few purposes: - To make the connected account the settlement merchant - To use a connected account’s branding in hosted resources (email receipts, invoices, and the customer portal) Read the following docs for requirements to using `on_behalf_of` and more information about how it affects payments on subscriptions: - For automatic transfers to the connected account, refer to the `on_behalf_of` parameter details in [Charge on behalf of a connected account](https://docs.stripe.com/connect/charges.md#on_behalf_of). - For information on how to transfer payments manually, refer to the Transfer Availability section in [Creating separate charges and transfers](https://docs.stripe.com/connect/separate-charges-and-transfers.md#settlement-merchant). - For a list of account capabilities required for processing payment methods, refer to [Payment method capabilities](https://docs.stripe.com/connect/account-capabilities.md#payment-methods). - For a list of branding options to enable on the connected account, refer to the `settings.branding` parameter details in the [API reference docs](https://docs.stripe.com/api/accounts/object.md#account_object-settings-branding) This example shows `on_behalf_of` for a new subscription using separate charges and transfers: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d customer="{{CUSTOMER_ID}}" \ -d on_behalf_of="{{CONNECTEDACCOUNT_ID}}" \ -d "items[0][price]"="{{PRICE_ID}}" ``` This example shows how to use `on_behalf_of` with a destination charge and application fee: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d on_behalf_of="{{CONNECTEDACCOUNT_ID}}" \ -d application_fee_percent=10 \ -d "transfer_data[destination]"="{{CONNECTEDACCOUNT_ID}}" \ -d "items[0][price]"="{{PRICE_ID}}" ``` ### Understand disconnect behavior When a connected account is disconnected from a platform, subscriptions aren’t automatically canceled. However, some aspects of payment collection may continue or cease to continue based on the charge type used. ### Direct charges After disconnect, subscriptions continue to run on the connected account. If the subscription was created with an `application_fee_percent`, the application fee continues to be collected by the platform after disconnect. Remove the `application_fee_percent` from the Subscription before a connected account disconnects from your platform. After disconnect, a connected account can clear the `application_fee_percent` parameter from existing Subscriptions through the API. ### Destination charges or separate charges and transfers After disconnect, existing subscriptions created as destination charges or separate charges and transfers continue to generate invoices, but they can’t transfer funds to a connected account. Before disconnecting, you should assist connected accounts with subscription migrations or cancel associated subscriptions. ### Destination charges with on_behalf_of When a connected account is disconnected from a platform, any `on_behalf_of` subscriptions won’t charge the customer on subscription invoices set to `charge_automatically`. We continue to generate subscription invoices for each cycle, but they remain drafts with `auto_advance` set to `false`. To continue collecting payment, you must reconnect with the disconnected account, or explicitly remove these fields from the subscription invoice and reattempt payment on these invoices. ### Integrate tax calculation and collection You need to first determine which entity is liable for tax. The entity that’s liable for tax might be your connected account or the platform, depending on your business model. To learn more, see [Stripe Tax with Connect](https://docs.stripe.com/tax/connect.md). ## See also - [Creating invoices](https://docs.stripe.com/invoicing/connect.md) - [Creating charges](https://docs.stripe.com/connect/charges.md) - [Share customers across accounts](https://docs.stripe.com/connect/cloning-customers-across-accounts.md) - [Multiple currencies](https://docs.stripe.com/connect/currencies.md)