Managing Plans

    Learn how to work with plans in more detail.

    Plans are at the heart of subscriptions, establishing the billing cycle, currency, and base cost. This guide covers plans in detail, changing and deleting plans, how to find customers by plan, and what you should know when it comes to working with local currencies.

    Plans in detail

    Plans have the following parameters:

    • id, a unique identifier. Unlike other IDs auto-generated by Stripe, you specify the plan ID. Each plan ID must be unique across all the plans in your Stripe account, although you can use the same plan ID in both live and test modes.

    • name, a user-friendly label for the plan that is seen by you in your Dashboard, by you on invoices, and by your customers on receipts (if you send them).

    • amount, what the customer is charged per subscription per interval.

    • interval, the billing period for the plan, which can range from a single day to a year. The interval options are day, week, month, and year. You can also use interval_count to set more customized intervals, such as billing a customer every 30 days or every 5 months.

    You can create a plan either via the API or through the Dashboard. The above image shows the Dashboard interface; the following code shows the corresponding API call:

    curl https://api.stripe.com/v1/plans \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d name="Pro Plan" \
       -d id=pro-monthly \
       -d interval=month \
       -d currency=usd \
       -d amount=3000
    
    # 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"
    
    plan = Stripe::Plan.create(
      :name => "Pro Plan",
      :id => "pro-monthly",
      :interval => "month",
      :currency => "usd",
      :amount => 3000,
    )
    
    # 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"
    
    plan = stripe.Plan.create(
      name="Basic Plan",
      id="basic-monthly",
      interval="month",
      currency="usd",
      amount=0,
    )
    
    // 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");
    
    $plan = \Stripe\Plan::create(array(
      "name" => "Basic Plan",
      "id" => "basic-monthly",
      "interval" => "month",
      "currency" => "usd",
      "amount" => 0,
    ));
    
    // 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("name", "Pro Plan");
    params.put("id", "pro-monthly");
    params.put("interval", "month");
    params.put("currency", "usd");
    params.put("amount", 3000);
    
    Plan plan = Plan.create(params);
    
    // 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 plan = stripe.plans.create({
      name: "Pro Plan",
      id: "pro-monthly",
      interval: "month",
      currency: "usd",
      amount: 3000,
    }, function(err, plan) {
      // 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.PlanParams{
      Name: "Pro Plan",
      Id: "pro-monthly",
      Interval: "month",
      Currency: "usd",
      Amount: 3000,
    }
    proPlan, err := plan.New(params)
    

    Changing and deleting plans

    Once a plan has been created, only the metadata and statement description can be modified; the amount, currency, and interval are fixed. Should you need to change any of these parameters, a new plan must be created instead.

    This restriction avoids the potential surprise and confusion that would arise from having different customers on the same plan but at different price points.

    If you only want to subscribe new customers to the new plan price, simply create a new plan. Having a new plan makes it clearer which customers are subscribed to each plan, as each plan’s ID is different.

    To switch customers over to new plan:

    1. Create a new plan with a new ID and new price, using the instructions above.
    2. Find all the customers on the old plan, using the instructions that follow.
    3. Update every subscription found in Step 2 to the new plan.

    There will likely be a proration impact of the change, as described in the upgrading and downgrading documentation. If you’d rather charge customers the full amount of the new plan, cancel their subscriptions before subscribing them to the new plan. Doing so also resets the customer’s billing cycle.

    Deleting a plan does not affect any existing subscribers of that plan, but new customers cannot be subscribed to it. We advise against deleting plans as having the historical plan information—even when no longer actively used—may be valuable.

    Finding customers by plan

    You can find customers currently subscribed to a plan via the Dashboard or the API.

    Using the Dashboard

    To find customers by plan in the Dashboard:

    1. Head to the Subscriptions page.
    2. Click Filter.
    3. In the filter dialog, check Plan, select the specific plan from the drop-down, and click Done.

    Using the API

    To find customer by plan via the API, provide a plan parameter in a list all subscriptions API call:

    curl https://api.stripe.com/v1/subscriptions \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d plan=pro-monthly \
       -G 
    
    # 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"
    
    Stripe::Subscription.all(
      :plan => "pro-monthly",
    )
    
    # 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"
    
    stripe.Subscription.all(
      plan="pro-monthly",
    )
    
    // 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");
    
    \Stripe\Subscription::all(array(
      "plan" => "pro-monthly",
    ));
    
    // 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("plan", "pro-monthly");
    
    SubscriptionCollection subscriptions = Subscription.all(params);
    
    // 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.subscriptions.list({
      plan: "pro-monthly",
    }, function(err, subscriptions) {
      // 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.SubListParams{
      Plan: "pro-monthly",
    }
    subscriptions := sub.List(params)
    

    Working with local currencies

    Stripe supports processing payments in 135+ currencies. This means you can create subscriptions in a customer’s local currency instead of always using your preferred currency. However, there are two issues to be aware of when using multiple currencies.

    First, a plan’s currency is set at the time of its creation and cannot be changed. To offer the same plan in multiple currencies, you have to create separate plans.

    Second, each Customer object in Stripe is set to a specific currency the first time any of the following occurs:

    • The customer is subscribed to a plan
    • An invoice is created for the customer
    • An invoice item is created for the customer
    • The customer’s balance is adjusted
    • A flat-rate coupon is attached to the customer (not a percent-off coupon)

    When any of the above occurs, the Customer object is set to the applicable currency. From that point on, the customer’s set currency cannot be changed nor can a subscription, invoice, invoice item, balance adjustment, or coupon in another currency be applied to that customer.

    The only way to change the currency you charge a user in is to create a new Customer object representing that user, attaching a payment method, and then pursuing the desired task in the right currency.

    Next steps

    Congrats! You’ve learned more about plans in Stripe. Some resources you might want to see next: