Configure optional items

Configuring optional items on a Checkout Session allows customers to add multiple optional products to their order during checkout. This can increase your average order value and revenue. For example, if you’re selling a subscription service, you might also want to offer optional add-ons to customers during checkout like a one-time setup fee and recurring priority support plan.

Create a Checkout Session with optional items

When creating a Checkout Session, you configure optional_items in the same way you configure line_items, specifying a price and quantity for each optional item you want to offer to the customer. You can offer up to 10 optional items on a single Checkout Session.

await stripe.checkout.sessions.create({
  // ...
  line_items: [
    {
      price: '{{PRICE_ID}}',
      quantity: 1,
    },
  ],
  optional_items: [
    {
      price: '{{OTHER_PRICE_ID}}',
      quantity: 1,
    },
    {
      price: '{{ANOTHER_PRICE_ID}}',
      quantity: 1,
    },
  ],
});

Allow customers to adjust quantity

You can also allow customers to adjust the quantity of optional items after adding them to their order by specifying adjustable_quantity, the same way you do for line items.

await stripe.checkout.sessions.create({
  // ...
  optional_items: [
    {
      price: '{{PRICE_ID}}',
      quantity: 1,
      adjustable_quantity: {
        enabled: true,
        minimum: 0,
        maximum: 10,
      },
    },
  ],
});

Customers can always remove optional items from their order, even if you specify a quantity or adjustable_quantity.minimum greater than 0.

Limitations

• Supports at most 10 optional items.
• Doesn’t support recurring optional items if a line item has a subscription upsell configured.
• Doesn’t support optional items using custom amounts or using optional items when a line item is using custom amounts.
• Not supported in setup mode.
• Doesn’t support recurring optional items in payment mode.
• The billing interval of any recurring optional items (monthly, yearly, etc) must match the interval of the recurring line items.
• Cross-sells configured in the Product catalog won’t appear on Checkout Sessions created with optional items.

Add a product-associated optional item

Use cross-sells to specify complementary products that you always want recommended as optional items at checkout. When you configure a cross-sell associated with a product, the optional item appears across all eligible Checkout Sessions with that product. Cross-sells won’t appear if you specify additional optional items on a payment link.

To configure a cross-sell:

1. On the Product catalog page, select your product.
2. On the product details page, under Cross-sells, find the product you want to cross-sell.

After you configure a cross-sell, the Checkout Sessions that contain your designated product automatically add the cross-sell as an optional item.