Mixed subscription checkout
INFO
Available since Shopware version 6.7.4.0
This guide describes how the so-called mixed carts for subscriptions work and how extensions should integrate with it. Mixed carts let customers buy subscription products and one‑time products during a single checkout while keeping subscription calculation isolated and predictable.
Please familiarize yourself with the concept first before continuing here.
Overview
Subscription line items are ordinary product line items in the main cart, but they carry subscription plan and interval IDs in their payload. During cart calculation, line items containing subscription plan and interval IDs in their payload are collected and grouped by plan and interval. For each group a derived managed subscription context and a managed subscription cart are created and calculated using the subscription cart calculation path. These represent the context and content of the upcoming generated subscription.
Managed subscription contexts and carts are persisted in the database as well. They are linked back to the main context by the subscription_cart database table.
Retrieving information
You can access the managed carts through the cart extension named subscriptionManagedCarts, which maps keys in the form <plan-id>-<interval-id> to their corresponding managed cart. The sales channel context extension named subscriptionManagedContexts provides the same mapping for managed sales channel contexts. The intended way of retrieving plan and interval IDs is to split the composite ID out of this mapping.
When an order is placed from a mixed cart, the order will contain an initialSubscriptions extension that includes all created subscriptions. As any subsequent orders are generated per subscription, the orders will contain a subscriptionId / subscription extension instead.
Manipulate mixed cart
With subscription mixed carts, you manipulate the main cart as you are used to. This is different from the separate checkout, where you manipulate a separate subscription cart directly, e.g. by subscription scoped cart processors or separate Store API routes. Therefore, to support mixed carts, your cart collectors and processors should process both subscription carts and regular carts, so they need to be tagged with subscription.cart.collector (or subscription.cart.processor) as well as shopware.cart.collector (or shopware.cart.processor). If you need to differentiate between main and subscription cart calculations, check the sales channel context for the subscription extension. If you need to differentiate between a mixed and a separate subscription cart calculation, check salesChannelContext.extensions.subscription.isManaged.
The cart processor Shopware\Commercial\Subscription\Checkout\Cart\Discount\SubscriptionDiscountProcessor is a good example how to add line items to mixed carts.
WARNING
We discourage the use of subscription collectors and processors for adding new line items only to subscription carts. Instead, always make sure to add line items to the main cart as well. This is because it's potentially confusing for customers, and handling line items in subscription carts missing in the main cart is more difficult. Instead, follow the steps described below to add additional line items.
If you still want to add line items to subscription carts only, please add a subscriber to the SubscriptionOrderLineItemRestoredEvent event to correctly show the line item in Shopware's after order process.
Adding subscription line items
To add a line item to a subscription cart, the relevant subscription plan and interval IDs must be added.
The following methods are available to do so via the Store-API:
- Add
lineItem.subscriptionPlanandlineItem.subscriptionIntervalIDs to a line item - Add
lineItem.subscriptionPlanandlineItem.subscriptionInterval-<plan-id>IDs to a line item (useful when submitting HTML forms) - Add
lineItem.payload.subscriptionPlanandlineItem.payload.subscriptionIntervalIDs to a line item's payload
Information added through the first two methods will be remapped to the line item's payload, as shown in the last method.
To do so via the backend, like in cart collectors or processors, the following methods are available:
- Add
lineItem.payload.subscriptionPlanandlineItem.payload.subscriptionIntervalIDs to a line items payload
Events
A mixed cart will fire all events like usual. Additionally, any event fired during the subscription cart calculation will be prefixed with subscription. like it is the case in the separate checkout.
INFO
Note that unlike the separate checkout, only the normal CheckoutOrderPlacedEvent but no 'subscription.' . CheckoutOrderPlacedEvent (or similar) will be fired, as the subscription carts are not placed as separate orders.
Mixed carts in the Storefront
To change the following Storefront pages if a mixed cart is present, the template scope mixed-subscription must be added to the page's Twig templates and subsequent Twig templates used:
frontend.checkout.cart.page/@Storefront/storefront/page/checkout/cart/index.html.twigfrontend.checkout.confirm.page/@Storefront/storefront/page/checkout/confirm/index.html.twigfrontend.checkout.register.page/@Storefront/storefront/page/checkout/address/index.html.twigfrontend.account.edit-order.page/@Storefront/storefront/page/account/order/index.html.twigfrontend.account.login.page/@Storefront/storefront/page/account/register/index.html.twigfrontend.account.register.page/@Storefront/storefront/page/account/register/index.html.twigfrontend.cart.offcanvas/@Storefront/storefront/component/checkout/offcanvas-cart.html.twig
Further information can be found in the dedicated guide here. The list can be changed through the subscription.routes.mixed-storefront-scope Symfony container parameter.
Besides the scope change in Twig templates, the following additional information is available in Twig templates:
