Creating Subscriptions

    With Connect, you can create subscriptions on behalf of connected accounts, optionally taking application fees in the process.

    Through Connect, you can create subscriptions on connected accounts. You can also take an application fee percentage on those subscription payments.

    Using subscriptions with Connect has these restrictions:

    • Both the customer and the plan must be created on the connected account (not your platform account)
    • Subscriptions must be created directly on the connected account (using the destination parameter is not supported)
    • Your platform can’t update or cancel a subscription it did not create
    • Your platform can’t add an application_fee to an invoice that it didn’t create or that contains invoice items it didn’t create

    Creating subscriptions

    Create a subscription on a connected account by performing a standard create subscription call while authenticated as the connected account. Again, both the customer and the plan must be defined on the connected account for this to work.

    curl https://api.stripe.com/v1/subscriptions \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d customer=cus_4fdAW5ftNQow1a \
       -d plan=pro-monthly \
       -H "Stripe-Account: {CONNECTED_STRIPE_ACCOUNT_ID}"
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    subscription = Stripe::Subscription.create({
      :customer => "cus_4fdAW5ftNQow1a",
      :plan => "pro-monthly",
    }, :stripe_account => {CONNECTED_STRIPE_ACCOUNT_ID})
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    subscription = stripe.Subscription.create(
      customer="cus_4fdAW5ftNQow1a",
      plan="pro-monthly",
      stripe_account="{CONNECTED_STRIPE_ACCOUNT_ID}",
    )
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    $subscription = \Stripe\Subscription::create(array(
      "customer" => "cus_4fdAW5ftNQow1a",
      "plan" => "pro-monthly",
    ), array("stripe_account" => "{CONNECTED_STRIPE_ACCOUNT_ID}"));
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
    
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("customer", "cus_4fdAW5ftNQow1a");
    params.put("plan", "pro-monthly");
    
    RequestOptions requestOptions = RequestOptions.builder().setStripeAccount({CONNECTED_STRIPE_ACCOUNT_ID}).build();
    Charge charge = Charge.create(params, requestOptions);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    var subscription = stripe.subscriptions.create({
      customer: "cus_4fdAW5ftNQow1a",
      plan: "pro-monthly",
    }, {
      stripe_account: "{CONNECTED_STRIPE_ACCOUNT_ID}",
    }, function(err, subscription) {
      // asynchronously called
    });
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.SubParams{
      Customer: "cus_4fdAW5ftNQow1a",
      Plan: "pro-monthly",
      StripeAccount: "{CONNECTED_STRIPE_ACCOUNT_ID}",
    }
    subscription, err := sub.New(params)
    
    

    As with creating direct charges on a connected account, you can create a customer on a connected account using a token created with either the platform’s or the connected account’s publishable key. You can also create a token using shared customers.

    Collecting fees on subscriptions

    When creating or updating a subscription, you can specify an application_fee_percent parameter as an integer between 1 and 100. Each billing period, Stripe takes that percentage off the final invoice amount—including any bundled invoice items, discounts, or account balance adjustments—as a fee for the platform (before any Stripe fees are charged).

    curl https://api.stripe.com/v1/subscriptions \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d customer=cus_4fdAW5ftNQow1a \
       -d plan=pro-monthly \
       -d application_fee_percent=10 \
       -H "Stripe-Account: {CONNECTED_STRIPE_ACCOUNT_ID}"
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    subscription = Stripe::Subscription.create({
      :customer => "cus_4fdAW5ftNQow1a",
      :plan => "pro-monthly",
      :application_fee_percent => 10,
    }, :stripe_account => {CONNECTED_STRIPE_ACCOUNT_ID})
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    subscription = stripe.Subscription.create(
      customer="cus_4fdAW5ftNQow1a",
      plan="pro-monthly",
      application_fee_percent=10,
      stripe_account="{CONNECTED_STRIPE_ACCOUNT_ID}",
    )
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    $subscription = \Stripe\Subscription::create(array(
      "customer" => "cus_4fdAW5ftNQow1a",
      "plan" => "pro-monthly",
      "application_fee_percent" => 10,
    ), array("stripe_account" => "{CONNECTED_STRIPE_ACCOUNT_ID}"));
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
    
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("customer", "cus_4fdAW5ftNQow1a");
    params.put("plan", "pro-monthly");
    params.put("application_fee_percent", 10);
    
    RequestOptions requestOptions = RequestOptions.builder().setStripeAccount({CONNECTED_STRIPE_ACCOUNT_ID}).build();
    Charge charge = Charge.create(params, requestOptions);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    var subscription = stripe.subscriptions.create({
      customer: "cus_4fdAW5ftNQow1a",
      plan: "pro-monthly",
      application_fee_percent: 10,
    }, {
      stripe_account: "{CONNECTED_STRIPE_ACCOUNT_ID}",
    }, function(err, subscription) {
      // asynchronously called
    });
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.SubParams{
      Customer: "cus_4fdAW5ftNQow1a",
      Plan: "pro-monthly",
      FeePercent: 10,
      StripeAccount: "{CONNECTED_STRIPE_ACCOUNT_ID}",
    }
    subscription, err := sub.New(params)
    
    

    For example, take this scenario:

    • The subscription cost per billing cycle is $30
    • There’s a $10 invoice item
    • A 50% coupon applies
    • The application_fee_percent is 10

    In that case, the total application fee taken is $2.00: ($30 + $10) * 50% * 10%.

    Application fees on subscriptions must be a percentage, as the amount billed via subscriptions often varies. You cannot set a flat amount for the application fee on a subscription, but can on an invoice as explained below.

    The application_fee_percent does not apply to invoices created outside of a subscription billing period. This includes proration invoice items that are immediately invoiced. In those cases, you should to set an application_fee on the invoice directly for the amount you’d like to charge.

    Working with invoices

    To charge a flat or dynamic fee, or any fee that can’t be automatically calculated with application_fee_percent, add an application_fee directly on an invoice:

    curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \
       -u {PLATFORM_SECRET_KEY}: \
       -d application_fee=100 \
       -H "Stripe-Account: {CONNECTED_STRIPE_ACCOUNT_ID}"
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    invoice = Stripe::Invoice.retrieve(
      {INVOICE_ID},
      :stripe_account => {CONNECTED_STRIPE_ACCOUNT_ID},
    )
    invoice.application_fee = 100
    invoice.save
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    invoice = stripe.Invoice.retrieve(
      {INVOICE_ID},
      stripe_account="{CONNECTED_STRIPE_ACCOUNT_ID}",
    )
    invoice.application_fee = 100
    invoice.save()
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    $invoice = StripeInvoice::retrieve(
      {INVOICE_ID}
    ), array("stripe_account" => "{CONNECTED_STRIPE_ACCOUNT_ID}"));
    $invoice->application_fee = 100; // amount in cents
    $invoice->save();
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
    
    RequestOptions requestOptions = RequestOptions.builder().setStripeAccount({CONNECTED_STRIPE_ACCOUNT_ID}).build();
    Invoice invoice = Invoice.retrieve({INVOICE_ID}, requestOptions);
    
    Map<String, Object> invoiceParams = new HashMap<String, Object>();
    invoiceParams.put("application_fee", 100);
    invoice.update(invoiceParams, requestOptions);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    stripe.invoices.update(
      {INVOICE_ID},
      {application_fee: 100},
      {stripe_account: CONNECTED_STRIPE_ACCOUNT_ID},
    }).then(function(invoice) {
      // asynchronously called
    });
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.InvoiceParams{
      Fee: 100,
      StripeAccount: "{CONNECTED_STRIPE_ACCOUNT_ID}",
    }
    invoice, err := invoice.Update(params)
    

    (Usually this is done programmatically upon receiving an invoice.created webhook notification, although you can separately create an invoice for pending invoice items and set an application fee on it.)

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

    Further reading

    Discover what other Connect functionality is available!