Magento 2 Subscriptions

Using subscriptions with Adobe Commerce and Magento Open Source


Subscriptions can help grow your business and provide a predictable revenue stream. To use subscriptions effectively, learn how to build your plans and subscription charges.

The first step is creating a plan. This allows you to define the terms of a subscription. Once a plan is created, you can create a subscription product and assign a plan to it. When a customer selects a subscription product, it creates an instance of a subscription that contains the specific details of that customer's subscription.

Step 1: Create a Plan

A plan defines the terms of a subscription, like charge frequency and amount. To set up a plan, go to the Magento console and configure the following fields:

Plan namePlan name set by the merchant
Is activePotential Values: Yes, No. Used to disable the use of a plan. Plans cannot be deleted using the BlueSnap API.
Charge frequencyControls how frequently a shopper is charged. Once set, this can not be changed.
CurrencyA plan can only have one currency. The options come from the site-wide currency configuration. Once set, this can not be changed.
Initial chargeIf you want to adjust the standard initial charge, enter a value here. If this field is left blank, there will be no initial charge.
Standard chargeThe recurring charge. Once set, this can not be changed.
Max chargesThis determines how many recurring payments the plan includes. If this field is left blank, it will default to none. Max charges do not include the initial payment when creating the subscription.
Grace periodIn case of payment failure, this is the number of days automatic retries will be attempted.
Available on websiteThe subscription will appear on the site selected here
Charge on ChangeDetermines whether subscriptions that are switched to this plan are charged immediately or on the next charge date.

If you have multiple store views with different currencies, you will need to create a plan for each currency. Be sure not to set the base currency as EUR and the display currency as USD. If the display or allowed currency differs from the store's base currency, prices will be displayed and stored incorrectly. It is best practice to ensure the configured currencies match.

If you have a product that is offered as a subscription with different charge frequency options, you will need to create a separate product and plan for each charge frequency. You can only associate one plan per product.

Step 2: Create a Subscription

A subscription defines the plan that is associated with a certain product and is configured at the product level. It can also refer to the specific details of the plan the shopper has chosen.

Is Product SubscriptionPotential Values: Yes, No
Subscription PlanThe plan the product currently uses. It provides payment frequency, price, and currency as values.
Related SubscriptionsAllows the association of upgrade and downgrade subscriptions. Works similarly to related products and upsell products in native Magento Open Source/Adobe Commerce.

You will need to individually configure each product you wish to offer a subscription with.

When a product is selected, the price is overridden by the plan price. If you are using the price from Magento in your theme, you need to consider that, as the module will override the template used when it detects a subscription product is being displayed.

Product Page

Navigate to the product page to define the details of your product. We recommend only using the Simple Product type for subscriptions. Keep in mind that it may not work with other types. The default pricing block on the product page will be replaced with the subscription details and price of the selected plan. Information from the block can be retrieved to display additional information. You can configure the following details:

  • Plan name: Value comes from the plan
  • Initial charge: If one exists, the value comes from the plan
  • Recurring charge: Value comes from the plan
  • Subscription period: Value comes from the plan.

If a field is null or zero it will not be displayed and you can override the template to configure the block display.

When configuring products, the default price on the product should be set higher than the intended plan price. If not, Magento Open Source/Adobe Commerce may show the product price instead of the configured price for the plan. This includes special prices.

Admin Experience

To configure the plan (add, edit, show) and show subscriptions and transactions, navigate to the BlueSnap Subscriptions section under the Sales section.

In the settings for payment gateway, you can control whether a user can change a subscription, cancel a subscription, or change the next payment date. You can also toggle between two different views:

  • Show Subscriptions: The standard view for subscriptions that have been created, includes their current status.
  • Show Transactions: Transaction records for each subscription. Represents both BlueSnap invoice ID/charge (initial and recurring) and its corresponding Magento order.

Customer Experience

Under the customers' My Account section your customers can view and manage their subscriptions. They can navigate to My Subscriptions to see a list of subscriptions they have created and click into a detailed view of the subscription. In the detailed view, they can manage the subscription using the following options: Cancel, Pause, Change Subscription Plan/Product, Change Payment Method.

Subscription Pricing

Include shipping within the price of your subscription and use the Free Shipping method.

Use Cases

  1. Time-limited subscriptions: Equal payments taken over a set charge frequency, for a set period. For example, 12 monthly payments of $20.
  2. Open-ended subscriptions: Perpetual payments that can ended by the user or the merchant. For example, a yearly subscription to a magazine.
  3. Initial charge: Set an initial charge for an amount different from the recurring charge. For example, a subscription with a discounted initial payment, with the first month charge set at $10 and the remaining months at set at $20. Another example could be using a subscription as a payment plan. You could take 50% of the total cost with the initial payment and then the remaining 50% in equal amounts over a set amount of time.

Best Practices & Tips

  • Upgrade/Downgrade Subscriptions: You can allow customers to upgrade and downgrade their subscriptions. For example, you could offer Bronze, Silver, and Gold options for a product or service. You can configure the product through the Alternative Products functionality to have other subscription products set as the next tier in the upgrade/downgrade path. Navigate to Related Subscriptions to configure this.
  • Instant Payment Notifications (IPNs/ Webhooks): The IPNs BlueSnap sends will be used to process inbound transactions and create orders against the subscription in the user's account. You may receive Recurring and Subscription Charge Failure IPNs.
  • Enable Vaulted Shoppers: If you are going to be using subscriptions, when setting up Magento make sure to select Yes for the Enable Vaulted Shoppers setting. Learn more.
  • Mixed Cart Purchases: Be careful when allowing customers to upgrade/downgrade their subscriptions. This feature should not be configured on websites that support mixed cart purchases (subscription and other non-subscription items in the same basket). Allowing changes to a customer's subscription when the initial charge was part of a mixed cart could lead to incorrectly calculated charges in case of a charge upon the switch. You can use mixed cart purchases if the plan is set to upgrade without a charge upon the switch.
  • Multiple Subscriptions in Cart: If you create an order on behalf of a customer, make sure you do not have more than one subscription product in the cart.
  • Discounts: By setting an initial charge in a plan, you can set a value for an initial subscription payment that is different from the recurring payment. We recommend you not use Basket Discounts. Instead, create products with subscriptions that have the discount included in the price.
  • Customers Updating their Subscriptions: You can configure whether a customer can: change a subscription (upgrade/downgrade), cancel a subscription, or pause the next payment. To give customers the ability to suspend a subscription, you will need to build support for that feature or instead disable the option.
  • Recurring Charges: If a recurring charge is different from the amount set in the plan, it will be reflected in the Magento order, but not in the BlueSnap recurring charge.
  • Deactivating vs Changing Plan: Deactivating a plan is different from changing the plan assigned to a product. Deactivating a plan might cause active subscriptions to fail. If you don't want to use a particular plan for future transactions, there are two solutions:
    1. Choose a different plan
    2. Unmark the product as a subscription product to revert it to a regular, non-subscription product
  • Cron Job: Cron for lookup should work without any additional setup required on your end. If there is missing data after subscription creation and we are unable to process it, then cron will be used to search for that information from relevant sources.
  • Suspected Fraud: If a subscription's initial transaction is flagged as suspect fraud, be sure to Approve/Reject through Magento (not through the BlueSnap Portal).
  • Refunds:
    • If you use the Refund Transaction link and complete a partial refund, the subscription transaction record is marked as Refunded. The link will not be available for any additional refund, so you can do request other partial refunds via Credit Memo.
      • We recommend to use the Refund Transaction option if you want to refund a BlueSnap invoice ID/charge that doesn’t have a corresponding Magento order.
    • Refund Subscriptions with Auth Only setting: If you have set your Payment Action set to Authorize Only, follow these steps to refund a subscription charge:
      1. Manually create an invoice in Magento
      2. Refund through BlueSnap. Make sure to uncheck the checkbox next to: _"When this box is checked we will STOP ALL further charges to this account. If you simply want to refund one charge but would like to continue to charge this customer automatically leave this box unchecked." This will ensure the subscription is not canceled.


BlueSnap does not support the following features for Magento 2 subscriptions:

  • ACH payments.
  • SEPA payments.
  • Additional charges, such as shipping cost or discounts.