Published and verified: 2026-09-24. Scope: optional product offers in Stripe-hosted Checkout, assessed from public documentation. Account and regional availability require separate confirmation. This is not an account test, a PayIn feature announcement, or a promise of higher revenue.
1. Decide whether the extra product is genuinely optional
A merchant offering a base subscription and an optional support package needs a different configuration review from a merchant collecting a compulsory setup charge. Stripe's optional_items lets a customer add complementary products during Checkout; each offer specifies a Price and quantity. Customers can always remove optional items, even when the configured quantity or adjustable minimum is greater than zero.[1]
Our recommendation: write “may decline” beside every candidate before choosing this feature. A positive minimum cannot turn an optional offer into a mandatory purchase. Keep compulsory charges out of the optional-offer decision. This guide concerns whether an offer is eligible and fits the Session's catalog budget, rather than inventory reservations, final-quantity fulfillment, or first-invoice setup-fee accounting.
2. Check mode and interface before selecting offers
Optional items are not supported in setup mode, and recurring optional items are not supported in payment mode. The Session creation API also says that optional_items cannot be set when ui_mode is custom.[1][2]
Recommended review order: identify the actual Checkout interface, record the Session mode, then classify each candidate Price as one-time or recurring. Do not infer support merely because another page uses the word “Checkout.” This article uses the official full-hosted-page variant; the general optional-items documentation URL is a variant index, not the complete implementation guide. For another interface, read its own current variant and API contract before reusing this configuration.
3. Apply compatibility filters to the whole proposed cart
Stripe does not support optional items with custom amounts, or optional items when a regular line item uses custom amounts. Recurring optional items are also unsupported when a line item has a subscription upsell configured. Any recurring optional item's billing interval must match that of the recurring line items.[1]
These restrictions are not solved by reducing an offer's quantity. As a proposed catalog rule, reject a monthly base subscription paired with an annual recurring optional offer rather than assuming Checkout will reconcile the schedules. Likewise, inspect the base cart for custom amounts and subscription-upsell configuration; checking only the add-on's Price is insufficient. Keep the reason for excluding a candidate so support can distinguish an incompatible offer from a missing catalog entry.
4. Count optional offers and combined capacity separately
A Session permits at most 10 optional items. That is an additional ceiling, not 10 extra places outside the normal cart limits. In payment mode, the combined number of line items and optional items is capped at 100. In subscription mode, the combined recurring category is capped at 20 and the combined one-time category is separately capped at 20.[2]
Count offered entries before customers select anything. The API describes limits on the combined configuration, not a budget that can be deferred until you know which offers were accepted.[2] The following are arithmetic examples of those documented ceilings, not executed API tests:
- Payment mode: 95 regular lines plus five optional entries reaches 100; adding a sixth exceeds the combined cap.
- Payment mode: one regular line plus 11 optional entries stays below 100 but exceeds the optional-entry cap.
- Subscription mode: 18 recurring regular lines plus two recurring offers reaches 20; a third recurring offer exceeds that category.
- Unused one-time capacity does not offset an over-limit recurring category.
Recommended implementation: calculate three values—optional-entry count, combined recurring count, and combined one-time count—then apply the relevant mode rules. Count entries rather than summing purchased units. A single offer with quantity five is not five different optional entries. Passing this count check establishes only numerical compatibility; it does not establish account eligibility or clear the other restrictions.
5. Choose explicit offers or catalog cross-sells deliberately
Stripe states that cross-sells configured in the Product catalog will not appear on Checkout Sessions created with optional items. The guide also describes product-associated cross-sells as a way to recommend complementary products across eligible Sessions containing that product.[1]
Therefore, our recommendation is to treat explicit Session offers and catalog recommendations as separate merchandising paths, not additive layers. If a familiar recommendation disappears after introducing optional_items, inspect that documented interaction before blaming a stale catalog. Record which path owns the recommendation and which team approves its removal. Do not promise that a catalog cross-sell will remain visible alongside a Session-specific list.
6. Review boundary cases before release
Suggested sandbox checks, not performed here: create an eligible hosted one-time cart with an optional accessory; decline it; add and then remove it despite a positive minimum; review the resulting customer-facing selection. Separately exercise 10 versus 11 offers, the payment-mode combined boundary, and each subscription category boundary. Include a custom-amount base item, a recurring offer in payment mode, a mismatched interval, and a subscription-upsell conflict as negative cases.
Record the intended interface, mode, Price classifications, exclusion reasons and calculated counts. Keep an error review separate from a successful numerical check: this guide does not prescribe exact error strings or claim tests returned them. Public search was attempted for this narrow integration problem, but retrieval restrictions and irrelevant results prevented independent community-demand verification. The article is grounded in the documented decision points, not estimated search volume or conversion gains.
Sources and dates
Official documentation checked 2026-09-24. Publication and update dates were not established. Regional and account eligibility are not established by this documentation review.
- [1] https://docs.stripe.com/payments/checkout/optional-items?payment-ui=stripe-hosted — Configure optional items — full hosted page
- [2] https://docs.stripe.com/api/checkout/sessions/create — Create a Checkout Session