Managing Products and 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. Every plan is attached to a product, which represents the application or service offered to customers. Products can have more than one plan, reflecting variations in price and duration—such as monthly and annual pricing at different rates.

    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.

    Products

    There are two kinds of products: goods and services. Goods are intended for use with the Orders API while services are for subscriptions. When creating a product, use the type parameter to specify the correct one. Service-type products have the following parameters:

    • name, the product’s name, meant to be displayable to the customer.
    • type, the product’s type, which should be service when working with subscriptions.
    • metadata, a mapping of arbitrary keys and values that you can use to store additional information about the service in a structured format.

    The following code demonstrates how to create a service-type product:

    curl https://api.stripe.com/v1/products \
       -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
       -d name="My SaaS Platform" \
       -d type=service
    
    # 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_4eC39HqLyjWDarjtT1zdp7dc"
    
    product = Stripe::Product.create({
        name: 'My SaaS Platform',
        type: 'service',
    })
    
    # 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_4eC39HqLyjWDarjtT1zdp7dc"
    
    product = stripe.Product.create(
      name='My SaaS Platform',
      type='service',
    )
    
    // 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_4eC39HqLyjWDarjtT1zdp7dc");
    
    $product = \Stripe\Product::create([
        'name' => 'My SaaS Platform',
        'type' => 'service',
    ]);
    
    // 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_4eC39HqLyjWDarjtT1zdp7dc";
    
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("name", "My SaaS Platform");
    params.put("type", "service");
    
    Product.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_4eC39HqLyjWDarjtT1zdp7dc");
    
    const product = stripe.products.create({
      name: 'My SaaS Platform',
      type: 'service',
    });
    
    // 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_4eC39HqLyjWDarjtT1zdp7dc"
    
    params := &stripe.ProductParams{
      Name: stripe.String("My SaaS Platform"),
      Type: stripe.String(string(stripe.ProductTypeService)),
    }
    prod, _ := product.New(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
    StripeConfiguration.SetApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    var options = new StripeProductCreateOptions {
        Name = "My SaaS Platform",
        Type = "service",
    };
    var service = new StripeProductService();
    StripeProduct product = service.Create(options);
    

    When creating a product through the API, the response includes an ID, which you can use to attach plans to the product.

    Plans in detail

    Plans have the following parameters:

    • product, either the ID of an existing product to associate with the plan or the properties to define a new product.
    • 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.
    • id, a unique identifier. This is auto-generated by Stripe. You can optionally override this value, but plan ID must be unique across all plans in your Stripe account. You can, however, use the same plan ID in both live and test modes.

    You can create a plan either via the API or through the Dashboard by selecting a product and then clicking + Add pricing plan. The following code shows how to perform the API call, passing the ID of an existing product:

    curl https://api.stripe.com/v1/plans \
       -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
       -d currency=usd \
       -d interval=month \
       -d product=prod_CHxGUqw1dyKsDM \
       -d nickname="Pro Plan" \
       -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_4eC39HqLyjWDarjtT1zdp7dc"
    
    plan = Stripe::Plan.create({
        currency: 'usd',
        interval: 'month',
        product: 'prod_CHxGUqw1dyKsDM',
        nickname: 'Pro Plan',
        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_4eC39HqLyjWDarjtT1zdp7dc"
    
    plan = stripe.Plan.create(
      currency='usd',
      interval='month',
      product='prod_CHxGUqw1dyKsDM',
      nickname='Pro Plan',
      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\Stripe::setApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    $plan = \Stripe\Plan::create([
        'currency' => 'usd',
        'interval' => 'month',
        'product' => 'prod_CHxGUqw1dyKsDM',
        'nickname' => 'Pro Plan',
        '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.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    Map<String, Object> params = new HashMap<>();
    params.put("currency", "usd");
    params.put("interval", "month");
    params.put("product", "prod_CHxGUqw1dyKsDM");
    params.put("nickname", "Pro Plan");
    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_4eC39HqLyjWDarjtT1zdp7dc");
    
    const plan = stripe.plans.create({
      currency: 'usd',
      interval: 'month',
      product: 'prod_CHxGUqw1dyKsDM',
      nickname: 'Pro Plan',
      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.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    params := &stripe.PlanParams{
      Amount: stripe.Int64(3000),
      Currency: stripe.String(string(stripe.CurrencyUSD)),
      Interval: stripe.String(string(stripe.PlanIntervalMonth)),
      Nickname: stripe.String("Pro Plan"),
      ProductID: stripe.String("prod_CHxGUqw1dyKsDM"),
    }
    pro, _ := plan.New(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
    StripeConfiguration.SetApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    var options = new StripePlanCreateOptions {
        Currency = "usd",
        Interval = "month",
        Nickname = "Pro Plan",
        Amount = 3000,
        ProductId = "prod_CHxGUqw1dyKsDM",
    };
    var service = new StripePlanService();
    StripePlan plan = service.Create(options);
    

    If you want to offer a basic plan alongside your pro plan, simply create a second plan attached to the same product and specify the desired characteristics.

    Changing and deleting plans

    Once a plan has been created, only the metadata and nickname 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 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. Should deleting a plan be absolutely appropriate, you can do so via the API.

    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. Navigate 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 customers by plan with the API, provide a plan parameter in a list all subscriptions API call:

    curl https://api.stripe.com/v1/subscriptions \
       -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
       -d plan=plan_CBb6IXqvTLXp3f
    
    # 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_4eC39HqLyjWDarjtT1zdp7dc"
    
    subscriptions = Stripe::Subscription.list({
        plan: 'plan_CBb6IXqvTLXp3f',
    })
    
    # 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_4eC39HqLyjWDarjtT1zdp7dc"
    
    subscriptions = stripe.Subscription.all(
      plan='plan_CBb6IXqvTLXp3f',
    )
    
    // 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_4eC39HqLyjWDarjtT1zdp7dc");
    
    $subscriptions = \Stripe\Subscription::all([
        'plan' => 'plan_CBb6IXqvTLXp3f',
    ]);
    
    // 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_4eC39HqLyjWDarjtT1zdp7dc";
    
    Map<String, Object> params = new HashMap<>();
    params.put("plan", "plan_CBb6IXqvTLXp3f");
    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_4eC39HqLyjWDarjtT1zdp7dc");
    
    const subscriptions = stripe.subscriptions.list({
      plan: 'plan_CBb6IXqvTLXp3f',
    });
    
    // 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_4eC39HqLyjWDarjtT1zdp7dc"
    
    params := &stripe.SubscriptionListParams{
      Plan: "plan_CBb6IXqvTLXp3f",
    }
    subscriptions, _ := sub.List(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
    StripeConfiguration.SetApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    var options = new StripeSubscriptionListOptions {
        PlanId = "plan_CBb6IXqvTLXp3f",
    };
    var service = new StripeSubscriptionService();
    StripeList<StripeSubscription> subscriptions = service.List(options);
    

    Using plans

    Conventional plans that charge a fixed amount on an interval are billed at the start of each billing cycle. With each invoice, the customer effectively pays for the next interval of service. In a metered plan, the price paid by the customer varies based on consumption during the billing interval, so the customer pays for their usage at the end.

    Subscriptions may include multiple plans, making it possible to combine metered billing and a fixed rate in the same subscription. In such cases, the customer is charged the fixed rate at the start of the billing cycle and is charged for their metered usage at the end of the billing cycle.

    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:

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.