Using subscriptions
How to enable and configure subscriptions
You can enable subscriptions for any Magento product from the product configuration page. When creating or editing a product, scroll down until you see the Stripe Subscriptions section:
Configuration options for subscriptions
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 front end 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 (i.e., the number of free days).
- Initial Fee: Enter an amount to be billed in addition to the subscription price.
You don’t need to do create a subscription plan in your Stripe account. A subscription plan is automatically created for this product when your customers check out.
Additional configuration
You can configure additional settings in the Payment Methods section of the Magento Admin Panel.
Payment method configuration options for subscriptions
Shipping Cost: You can configure the shipping cost to create only one charge (when the customer places the order), or on a recurring basis. When charged on a recurring basis, it’s added to the subscription invoice for every billing period, as shown below:
Summary view of a subscription invoice
Viewing or canceling subscriptions
When customers navigate to their account, they can view their purchased subscriptions by clicking the My Subscriptions link on the sidebar:
Viewing active subscriptions
Customers can view or cancel their subscriptions and edit their shipping address from here. When they edit their shipping address, it’s not changed on the original order, only the metadata is updated on the actual subscription.
Creating recurring subscription orders using Stripe webhooks
When you create a monthly subscription for a customer, Stripe issues an invoice every month, which is automatically paid in your Stripe account. If you have configured webhooks, Magento can receive notifications from Stripe that an invoice has been created, and will automatically create a new order for that subscription product in your Magento Admin Panel. If the customer originally placed the order with multiple subscriptions and products in the same cart, then recurring orders will be generated separately for each subscription in the original order. Initial subscription fees will be dropped from the recurring orders, and shipping/tax details will be recalculated for the individual recurring subscription product.
Creating a configurable subscription
You can find two examples of configurable subscriptions on the demo server. The two products were created in Magento as Configurable Products and have both Customizable Options and configurations under each of their product pages.
Use Customizable Options when you need to offer different prices for the same product. For example, for the Coffee Beans example, you can select a custom bag size which increases the subscription price if a larger bag is selected.
Use Configurations when you need to offer subscriptions of different frequencies to the customer. The Dropdown and Text Swatch controls allow the customer to select between One-off, Monthly, or Quarterly subscriptions.
You can review how these products have been configured in the Magento Admin Panel:
The product catalog includes all the configured products.
Configurable Dropdown Example
- Simple Single Purchase Product
- Simple Monthly Subscription Product
- Simple Quarterly Subscription Product
Configurable Text Swatch Example
- Simple One-off Purchase Product
- Simple Monthly Subscription Product
- Simple Quarterly Subscription Product
In the example above, each Simple Product, created automatically by Magento, also has a subscription enabled and configured. Each product is grouped together through Configurations, which you create manually.
To create a configurable product:
- Create a new product from the Catalog (it can be simple or virtual product).
- Scroll down and find the Configurations tab.
Creating a new product with a configuration
- Click Create Configurations.
Creating a product configuration
- Create a new attribute called subscription and make sure it’s set to Global under the Advanced Attribute Properties tab (example). You can also use Advanced Attribute Properties to determine whether you want this attribute to be a Dropdown or a Text Swatch (example).
- Under Manage Options, add the values that will appear in the dropdown or text swatch. For text swatches, you must also complete the Swatch column.
Manage the swatch options
- Under the Manage Labels tab, add whatever you want the customer to see on the product page. (e.g., “Subscribe and save 5%”).
- If you’re configuring the attribute as a Text Swatch, you can enable Used in product listing under Advanced Attribute Properties so that it appears in the catalog in a similar manner as the demo server.
- Save the attribute. It’s now in the attributes list where you can select it and click Next.
- Select all of the attribute values on the next page and complete the steps until you are back on the product page.
Current Configurations
- Magento then creates the simple products for you based on the attribute options. You can set the prices and product images at this step from the Configurations tab.
- Navigate back to the products catalog and select each of the newly created subscription products.
- Make sure that the Subscription attribute of each product has the correct value:
Configure the Subscription attribute
- Enable and configure each product’s subscription from the Stripe Subscriptions tab.
The Stripe Subscriptions options
Changing a customer’s subscription
If you plan to increase or reduce the subscription price for a specific product, or change the shipping cost, product name, or tax rates of an order, you can migrate existing subscriptions from an old plan to a new one using a CLI command within the Stripe module.
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 order totals are recalculated based on the new tax rules, shipping method, price changes, etc. If the original order had any discounts, those are reapplied on the new order. The initial fees are removed completely.
Successfully placing the order cancels the original order, including the original_product_id. The original order is marked with a comment that it’s been migrated to a new order, and that the associated subscription will be canceled 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 order can’t be placed 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 only the order totals will be recalculated. 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 (because we won’t have a shipping address).
The order ID parameters are optional. If they’re not specified, the script processes all orders in Magento from all store views and all Stripe modes. If you have multiple Stripe accounts configured, subscriptions from all Stripe accounts are migrated correctly.