# Subscriptions with multiple products

Create subscriptions with multiple products, all billed in a single invoice.

If you offer multiple products or want to charge different amounts for the same product, you can attach multiple products to a subscription.
This generates a single *invoice* each billing period that combines every price.
Only a single payment for that invoice is required, reducing your costs and the number of charges your customer sees.

## Creating multiple-product subscriptions 

Create multiple-product subscriptions on a customer using the `items` parameter. Provide the `price` and, optionally, a `quantity` (when using a value other than 1), for each product:

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new SubscriptionCreateOptions
{
    Customer = "<<customer>>",
    Items = new List<SubscriptionItemOptions>
    {
        new SubscriptionItemOptions { Price = "price_CBXbz9i7AIOTzr" },
        new SubscriptionItemOptions { Price = "price_IFuCu48Snc02bc", Quantity = 2 },
    },
};
var service = new SubscriptionService();
Subscription subscription = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.SubscriptionParams{
  Customer: stripe.String("<<customer>>"),
  Items: []*stripe.SubscriptionItemsParams{
    &stripe.SubscriptionItemsParams{Price: stripe.String("price_CBXbz9i7AIOTzr")},
    &stripe.SubscriptionItemsParams{
      Price: stripe.String("price_IFuCu48Snc02bc"),
      Quantity: stripe.Int64(2),
    },
  },
};
result, err := subscription.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SubscriptionCreateParams params =
  SubscriptionCreateParams.builder()
    .setCustomer("<<customer>>")
    .addItem(SubscriptionCreateParams.Item.builder().setPrice("price_CBXbz9i7AIOTzr").build())
    .addItem(
      SubscriptionCreateParams.Item.builder()
        .setPrice("price_IFuCu48Snc02bc")
        .setQuantity(2L)
        .build()
    )
    .build();

Subscription subscription = Subscription.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const subscription = await stripe.subscriptions.create({
  customer: '<<customer>>',
  items: [
    {
      price: 'price_CBXbz9i7AIOTzr',
    },
    {
      price: 'price_IFuCu48Snc02bc',
      quantity: 2,
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

subscription = stripe.Subscription.create(
  customer="<<customer>>",
  items=[{"price": "price_CBXbz9i7AIOTzr"}, {"price": "price_IFuCu48Snc02bc", "quantity": 2}],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$subscription = $stripe->subscriptions->create([
  'customer' => '<<customer>>',
  'items' => [
    ['price' => 'price_CBXbz9i7AIOTzr'],
    [
      'price' => 'price_IFuCu48Snc02bc',
      'quantity' => 2,
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

subscription = Stripe::Subscription.create({
  customer: '<<customer>>',
  items: [
    {price: 'price_CBXbz9i7AIOTzr'},
    {
      price: 'price_IFuCu48Snc02bc',
      quantity: 2,
    },
  ],
})
```

The response includes a list of all the subscription items, prices, and quantities:

```json
{
  "id": "sub_CZEpS1Zt9QLxdo",
  "object": "subscription",
  ...
  "items": {
    "object": "list",
    "data": [
      {
        "id": "si_H1yPnAVzP9vDRW",
        "object": "subscription_item",
        "created": 1585939321,
        "metadata": {
        },
        "price": {
          "id": "price_H1c8v1liEvrfcd",
          "object": "price",
          "active": true,
          "billing_scheme": "per_unit",
          "created": 1585856460,
          "currency": "usd",
          "livemode": false,
          "lookup_key": null,
          "metadata": {
          },
          "nickname": null,
          "product": "prod_H1c7exjJHbC4sr",
          "recurring": {
            "interval": "month",
            "interval_count": 1,
            "trial_period_days": null,
            "usage_type": "licensed"
          },
          "tiers": null,
          "tiers_mode": null,
          "transform_quantity": null,
          "type": "recurring",
          "unit_amount": 1000,
          "unit_amount_decimal": "1000"
        },
        "quantity": 1,
        "subscription": "sub_H1yPRslJXa4TUt",
        "tax_rates": [
        ]
      },
      {
        "id": "si_H1yPu4fSjq3oqM",
        "object": "subscription_item",
        "created": 1585939321,
        "metadata": {
        },
        "price": {
          "id": "price_H1yCssogQ6gtx1",
          "object": "price",
          "active": true,
          "billing_scheme": "per_unit",
          "created": 1585938535,
          "currency": "usd",
          "livemode": false,
          "lookup_key": null,
          "metadata": {
          },
          "nickname": null,
          "product": "prod_H1c7exjJHbC4sr",
          "recurring": {
            "interval": "month",
            "interval_count": 1,
            "trial_period_days": null,
            "usage_type": "licensed"
          },
          "tiers": null,
          "tiers_mode": null,
          "transform_quantity": null,
          "type": "recurring",
          "unit_amount": 2000,
          "unit_amount_decimal": "2000"
        },
        "quantity": 2,
        "subscription": "sub_H1yPRslJXa4TUt",
        "tax_rates": [
        ]
      }
    ]
  },
  ...
}
```

## Billing periods with multiple prices

Conventional prices that charge a fixed amount on an interval are billed at the start of each [billing cycle](https://docs.stripe.com/billing/subscriptions/billing-cycle.md). With each invoice, the customer effectively pays for the next interval of service. With [metered billing](https://docs.stripe.com/products-prices/pricing-models.md#usage-based-pricing), the amount paid by the customer varies based on consumption during the billing cycle, so the customer pays for their usage at the end.

When a subscription combines a fixed rate with metered billing, metered usage from the previous billing cycle is charged alongside the fixed rate for the new billing cycle at the start of each interval. The metered billing and fixed rate are combined in a single invoice.

## Restrictions 

To subscribe a customer to multiple subscriptions with different billing intervals or trial periods, use our [multiple subscriptions](https://docs.stripe.com/billing/subscriptions/multiple-products.md#multiple-subscriptions-for-a-customer) approach.

Since using multiple products with a subscription results in a single invoice and payment, all of the prices for those products must use the same currency and have the same billing interval. You are also limited to 20 products in a single subscription.

## Discounts, taxes, and trial periods 

When using multiple products, you can also create discounts, charge taxes, and use trial periods as you would with a single-product subscription.
Provide these as top-level arguments to the create or update subscription call, as they apply to the subscription at large:

When you create a subscription by passing prices into the `items` attribute, it will ignore any trial period that is specified on the individual prices. The trial period is only respected if you create a subscription with a single price using the legacy plan attribute.

## Multiple subscriptions for a customer

You can simultaneously create multiple subscriptions for a single customer. This capability is useful when you want to make it possible for your customers to subscribe to multiple products with separate intervals. Each subscription has its own separate billing cycle, invoice, and charge—even if the underlying prices have the same billing interval.

Create multiple subscriptions on a customer by using the same [create subscription](https://docs.stripe.com/api.md#create_subscription) code:

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new SubscriptionCreateOptions
{
    Customer = "cus_4fdAW5ftNQow1a",
    Items = new List<SubscriptionItemOptions>
    {
        new SubscriptionItemOptions { Price = "price_CZB2krKbBDOkTS" },
    },
};
var service = new SubscriptionService();
Subscription subscription = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.SubscriptionParams{
  Customer: stripe.String("cus_4fdAW5ftNQow1a"),
  Items: []*stripe.SubscriptionItemsParams{
    &stripe.SubscriptionItemsParams{Price: stripe.String("price_CZB2krKbBDOkTS")},
  },
};
result, err := subscription.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SubscriptionCreateParams params =
  SubscriptionCreateParams.builder()
    .setCustomer("cus_4fdAW5ftNQow1a")
    .addItem(SubscriptionCreateParams.Item.builder().setPrice("price_CZB2krKbBDOkTS").build())
    .build();

Subscription subscription = Subscription.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const subscription = await stripe.subscriptions.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [
    {
      price: 'price_CZB2krKbBDOkTS',
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

subscription = stripe.Subscription.create(
  customer="cus_4fdAW5ftNQow1a",
  items=[{"price": "price_CZB2krKbBDOkTS"}],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$subscription = $stripe->subscriptions->create([
  'customer' => 'cus_4fdAW5ftNQow1a',
  'items' => [['price' => 'price_CZB2krKbBDOkTS']],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

subscription = Stripe::Subscription.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [{price: 'price_CZB2krKbBDOkTS'}],
})
```

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new SubscriptionCreateOptions
{
    Customer = "cus_4fdAW5ftNQow1a",
    Items = new List<SubscriptionItemOptions>
    {
        new SubscriptionItemOptions { Price = "price_CZB1AX3KOacNJw" },
    },
};
var service = new SubscriptionService();
Subscription subscription = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.SubscriptionParams{
  Customer: stripe.String("cus_4fdAW5ftNQow1a"),
  Items: []*stripe.SubscriptionItemsParams{
    &stripe.SubscriptionItemsParams{Price: stripe.String("price_CZB1AX3KOacNJw")},
  },
};
result, err := subscription.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SubscriptionCreateParams params =
  SubscriptionCreateParams.builder()
    .setCustomer("cus_4fdAW5ftNQow1a")
    .addItem(SubscriptionCreateParams.Item.builder().setPrice("price_CZB1AX3KOacNJw").build())
    .build();

Subscription subscription = Subscription.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const subscription = await stripe.subscriptions.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [
    {
      price: 'price_CZB1AX3KOacNJw',
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

subscription = stripe.Subscription.create(
  customer="cus_4fdAW5ftNQow1a",
  items=[{"price": "price_CZB1AX3KOacNJw"}],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$subscription = $stripe->subscriptions->create([
  'customer' => 'cus_4fdAW5ftNQow1a',
  'items' => [['price' => 'price_CZB1AX3KOacNJw']],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

subscription = Stripe::Subscription.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [{price: 'price_CZB1AX3KOacNJw'}],
})
```

### Using quantities instead

If you create multiple subscriptions with the same price, each subscription is independent, including payments and billing cycles. If that’s not what you want, create a single subscription using [multiple quantities](https://docs.stripe.com/billing/subscriptions/quantities.md) instead.

A customer can be subscribed to multiple products or even to a single product multiple times. Each subscription has a unique ID and its state is handled independently from the customer’s other subscriptions. Each subscription also has its own independent billing cycle, based on the [billing cycle anchor](https://docs.stripe.com/billing/subscriptions/billing-cycle.md) of the subscription.

When a customer has multiple subscriptions, the `Customer` object’s `subscriptions` property provides a list of every subscription:

```json
{
  "id": "cus_4fdAW5ftNQow1a",
  "object": "customer",
  "subscriptions": {
    "object": "list",
    "data": [
      {
        "id": "sub_9RRl3XywPg2P5H",
        "object": "subscription",
        ...
        "price": {
          "id": "price_CZB2krKbBDOkTS",
          "object": "price",
          "amount": 2995,
          ...
        }
      },
      {
        "id": "sub_9RRlIq2t9obFLI",
        "object": "subscription",
        ...
        "price": {
          "id": "price_CZB1AX3KOacNJw",
          "object": "price",
          "amount": 1295,
          ...
        }
      }
    ]
    ...
  }
  ...
}
```

## See Also

* [Setting quantities](https://docs.stripe.com/billing/subscriptions/quantities.md)
* [Use trial periods](https://docs.stripe.com/billing/subscriptions/trials.md)
* [Subscriptions API](https://docs.stripe.com/api.md#create_subscription)