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.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "optional_items[0][price]"=
{{PRICE_ID}} \
  -d "optional_items[0][quantity]"=1 \
  -d "optional_items[1][price]"=
{{PRICE_ID}} \
  -d "optional_items[1][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.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "optional_items[0][price]"=
{{PRICE_ID}} \
  -d "optional_items[0][quantity]"=1 \
  -d "optional_items[0][adjustable_quantity][enabled]"=true \
  -d "optional_items[0][adjustable_quantity][minimum]"=0 \
  -d "optional_items[0][adjustable_quantity][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.