Once a customer adds a subscription item to their cart, the cart needs to reflect the subscription context clearly and enforce the constraints required by the checkout flow.
Purchase mode
The cart’s purchase mode is derived from line item metadata. Three modes are possible:
| Mode | Condition |
|---|
one-time | No subscription line items in the cart |
subscription | All line items are subscription items |
mixed | Cart contains both subscription and one-time items |
getCartPurchaseMode(cart) to derive the current mode from line item metadata and drive your cart UI accordingly.
Displaying subscription items
For each subscription line item, show the billing cadence alongside the product. The cadence is stored in the line item’s metadata fields frequency_interval and frequency_value:
const isSubscription = item.metadata?.is_subscription === true;
const interval = item.metadata?.frequency_interval; // e.g. "month"
const value = item.metadata?.frequency_value; // e.g. 1
Mixed cart guard
Mixed carts are not supported in the current release. If the cart contains both subscription and one-time items, disable the checkout CTA and show a clear explanation to the customer.
if (purchaseMode === "mixed") {
// Disable checkout, show limitation message
}
If a customer wants to purchase a subscription item and a one-time item together, they need to use separate carts and complete them through their respective checkout flows.
Cart CTA
Change the cart’s call-to-action label based on the current purchase mode to set the right expectation before checkout:
| Mode | Suggested CTA |
|---|
one-time | ”Proceed to checkout” |
subscription | ”Proceed to subscription checkout” |
mixed | Disabled — show mixed cart message |
Next step
When the customer proceeds from a subscription cart, complete the order through the Subscription Checkout flow instead of the standard Medusa cart-complete route. 
