Using subscriptions

Learn how to configure the Stripe Connector for Adobe Commerce to enable subscriptions for any Adobe Commerce product.

How subscriptions work

You can turn any virtual or simple Adobe Commerce product into a subscription product from its configuration page in your admin panel. When a customer buys a subscription product, the module registers a recurring payment against that order using Stripe Billing. Stripe manages this subscription, attempting payment collection on a recurring basis based on the subscription settings in Adobe Commerce. Stripe can also notify the customer if the payment fails and ask them to update their billing details. You can control this in your Subscriptions and emails settings.

On payment success, your website receives a webhook notification from Stripe. The module automatically creates a new order in your Adobe Commerce admin panel for each renewal. These recurring orders don’t include the initial subscription fees, and the module recalculates the shipping and tax amounts for each individual recurring subscription product.

How to enable and configure subscriptions

You can enable subscriptions for any Adobe Commerce product from the product configuration page. When creating or editing a product, scroll down until you see the Stripe Subscriptions section:

Here, you have the following options:

Subscription Enabled: Turn this on to convert this product into a subscription.
Frequency: Select Days, Weeks, Months, or Years. The customer frontend displays whatever you select here for the frequency. If you prefer to display 30 Days instead of 1 Month, set this to Days instead. If you select Days, the subscription is also created in days in your Stripe account.
Repeat Every: This number determines the length of the billing cycle for a subscription using the frequency defined above. For example, if you selected Days for the Frequency setting, billing occurs every 30 days.
Trial Days: Enter the number of days before the first charge for the subscription (that is, the number of free days).
Initial Fee: Enter an amount to charge in addition to the subscription price.

You don’t need to create a subscription plan in your Stripe account. A subscription plan is automatically created for this product when your customers check out.

Configurable subscriptions

You can use Magento configurable products to offer multiple options to your customers for a single product. Customers can choose their preferred option using either a drop-down, a visual swatch, or a text swatch. Each option can be a simple or virtual product and that product can itself be a subscription.

Go to Stores > Attributes > Product.
Create an attribute and choose your preferred input type and labels.
Make sure to set the attribute to be on the Global scope.
Go to Stores > Attributes > Attribute Set and add the attribute to an attribute set.
Add the attribute set to your single products.
You can now create a configurable product using the single products updated above.

Bundled subscriptions

Adobe Commerce allows you to bundle products when you want to sell multiple products together. This prevents customers from removing an individual product from the cart before checkout.

When a bundle product includes at least one subscription, Stripe treats the price of the entire bundle as the subscription price. For recurring payments, Stripe collects both the amount of the entire bundle item and the individual subscription item of the bundle.

After payment collection, Adobe Commerce automatically creates a recurring order that includes the entire bundle item (the subscription items and regular items from the original order). Inventory is then processed for the subscription and the other products in the bundle. This contrasts with carts that include subscriptions and regular products separately. In that case, recurring orders only include the subscription product.

If you want to combine a subscription product with a regular product and only bill the subscription product in the next cycle, you can use grouped products. Alternatively, you can configure an initial fee for the subscription when there’s no inventory to process.

Switching subscription plans

Customers can switch between two or more plans as long as they belong to the same configurable product.

The customer logs into their account and goes to My subscriptions.
They select the subscription they want to change and click Change subscription.
The module automatically filters any non-subscription options within that configurable product and displays the rest to the customer.
They choose the new plan and confirm the new price in the checkout page to place the order.

You can enable or disable switching plans for each configurable product separately or you can use the global setting under Stores > Configuration > Sales > Payment Methods > Stripe > Subscriptions.

Prorations for virtual subscriptions

The module supports prorations for virtual subscriptions. You can enable prorations for upgrades or downgrades separately.

The module compares what both the current and new plan cost for a 30-day period to determine whether or not it’s an upgrade or downgrade. If the cost of the new plan is lower, we consider it a downgrade. If the price remains the same or if it’s higher, we consider it an upgrade.

For downgrades, we create a refund that we record as a credit memo on the original order.
For upgrades that require an extra payment, we immediately create a new order with the prorated amount for the remainder of the billing period.
For upgrades with the same cost, there’s no payment or refund and we add a comment to the original order to indicate that the customer changed their subscription.

In all three cases, the module creates the renewal order with the new plan at the next billing cycle.

Changing customer subscriptions in bulk from the command line

You can increase or reduce the subscription price for a specific product, or change the shipping cost, product name, or tax rates of an order. To do so, you must migrate existing subscriptions from an old plan to a new one using a CLI command within the Stripe module.

Command Line

php bin/magento stripe:subscriptions:migrate-subscription-price <original_product_id> <new_product_id> [<starting_order_id> [<ending_order_id>]]

This creates a new order for new_product_id as if the customer placed the order during checkout. The billing and shipping details are the same as the initial order, and it uses the same payment method for the subscription.

The module recalculates the order totals based on the new tax rules, shipping method, price changes, and so on. If the original order had any discounts, they also apply to the new order. The total doesn’t include any of the initial fees.

Successfully placing the order cancels the original order, including the original_product_id. The module adds a comment to the original order mentioning the migration to a new order, and the cancellation of the associated subscription in Stripe. The customer also receives a new order email that tells them their subscription billing details have changed. They can review the new totals in the same email.

If the module can’t place the order for any reason, the built-in rollback system cancels the new order creation and leaves the original order intact.

You can use the original_product_id as the new_product_id, which means that the module only recalculates the order totals. It’s possible to migrate from simple subscription products (physical products with a single SKU) to virtual subscription products, but not the other way around. This limitation is because physical products require a shipping address but virtual products don’t.

The order ID parameters are optional. If they’re not specified, the script processes all orders in your website from all store views and all Stripe modes. If you have multiple Stripe accounts configured, the script migrates subscriptions from all Stripe accounts.

Migrate Stripe Subscriptions from another platform to Adobe Commerce

To migrate subscriptions from another platform, you need to perform the following tasks:

Create a mapping between your Adobe Commerce customer IDs and the Stripe customer IDs in the “stripe_customers” database table of Adobe Commerce. You can do this with the following SQL statement in your database:

INSERT INTO stripe_customers(customer_id, stripe_id, customer_email) VALUES ('2', 'cus_xxxxxxxxxx', 'janedoe@example.com');

Create and configure all subscription products for old orders from the Subscriptions by Stripe tab under each product’s configuration page:

Migrate the orders from your old platform to Adobe Commerce. If you plan on creating these manually from the Adobe Commerce admin area, you can use the Check / Money Order payment method so it doesn’t collect a live payment. After you finish the order migration, you can then replace this payment method with Stripe using the following SQL command:

UPDATE sales_order_payment SET method='stripe_payments' WHERE method='checkmo';

After creating the orders and products successfully in Adobe Commerce, update the existing Subscriptions in your Stripe account to set the following metadata:

Note

See also how to create or update subscriptions.

Test the creation of recurring orders based on subscription renewals:

Check that you have at least one configured webhook in your Stripe dashboard under Developers > Webhooks.
From your Stripe Events section, locate an event that you want to test. The event type must be invoice.payment_succeeded and the Invoice must belong to a Subscription.
From your Magento root directory, trigger the event with the following command: bin/magento stripe:webhooks:process-event <event_id>.
Make sure there were no errors in the console and that the module created a recurring subscription order in Adobe Commerce.