Stripe Subscriptions - Magento 2 - Documentation

About

Stripe Subscriptions is an optional add-on to Stripe Payments. It extends its capabilities to allow merchants to sell subscriptions using the Stripe payment gateway. This is the documentation for installing, configuring and using this add-on on Magento® 2.

For the most up to date documentation, you can always visit the online version of this documentation by clicking here.

Installation

If you purchased from our website

Warning: We recommend that you test the module on a testing server before installing it on your live web server. Please see the Troubleshooting section if you come across any installation issue.

  1. Because Stripe Subscriptions is an add-on to Stripe Payments, this means that you must first have Stripe Payments installed before installing this module. To install Stripe Payments, please see it's installation instructions.
  2. Once Stripe Payments is installed, if you haven’t done so already, please download Stripe Subscriptions from the account section or through the email that was sent to you when you purchased the module.
  3. Extract the file into your Magento root directory. The module will be installed under app/code/Cryozonic/StripePayments/
    tar -xvf cryozonic_stripesubscriptions-1.0.0.tgz
  4. Enable the module by running the following commands:
    php bin/magento setup:upgrade
    php bin/magento cache:flush
  5. If you are running Magento in production mode, you will also need to deploy the module's static files using the following command:
    php bin/magento setup:static-content:deploy
  6. If you are upgrading from a previous version, you will also need to run:
    php bin/magento module:enable Cryozonic_StripeSubscriptions

If you purchased from the Magento marketplace

Warning: We recommend that you test the module on a testing server before installing it on your live web server. Please see the Troubleshooting section if you come across any installation issue.

  1. As a minimum requirement, you will need cron running and fully functional for the installation. If you have not set up cron already, please follow the official instructions from Magento before proceeding.
  2. Ensure that your web server has full write access to the entire Magento directory. Official instructions can be found here. However the simplest way is to change the ownership of the Magento directory to the same user under which the web server is running. This can be done with:
    $ chown –R <www-username> /magento_directory
  3. Navigate to the Setup Wizard at http://yourdomain.com/admin/admin/backendapp/redirect/app/setup/
  4. To access your purchase from the marketplace, you will need to enter your Magento Marketplace authentication keys. If you haven't done so already, please follow these instructions.
  5. From the Setup Wizard page, click the Component Manager icon
  6. In the top section of the page, you will see a New Purchases section with an Install link underneath. Click the Install link and follow the instructions to install the module.
  7. The installation can take up to 5-6 minutes for cron to run its full cycle, upgrade Magento, re-deploy the static assets, recompile the code etc. Please be patient and leave the installation to finish without closing the window.
  8. If for any reason the installation takes unusually long, or it gets stuck at "Update pending", check for errors in var/log/update.log. Alternatively, you can run the cron commands manually from a shell without the pipes at the end so that errors are be displayed in the shell. If the command succeeds, the contents of the files under var/.update_* will also be updated. If any errors occur, simply contact us at info@cryozonic.com with details on what happened so that we can help you complete the installation.

Uninstall

If you purchased from our website

  1. From a terminal, run the following commands:
    php bin/magento module:disable --clear-static-content Cryozonic_StripeSubscriptions
    rm -rf app/code/Cryozonic/StripeSubscriptions
  2. If you are uninstalling PERMANENTLY (i.e. not upgrading to a newer version), you should also run the following database SQL statements:
    DELETE FROM eav_attribute WHERE attribute_code like "cryozonic_%";
    DELETE FROM eav_attribute_group WHERE attribute_group_code like "stripe-%";
    DROP TABLE cryozonic_stripe_customers;
    DELETE FROM setup_module WHERE module = 'Cryozonic_StripeSubscriptions';

If you purchased from the Magento marketplace

  1. Navigate to the Setup Wizard at http://yourdomain.com/admin/admin/backendapp/redirect/app/setup/
  2. Click the Component Manager icon
  3. On the right hand side column, you will see a dropdown with an Uninstall link. Click the Uninstall link and follow the instructions to uninstall the module.

    Magento 2 Uninstall Module

  4. If you are uninstalling PERMANENTLY (i.e. not upgrading to a newer version), you should also run the following database SQL statements:
    DELETE FROM eav_attribute WHERE attribute_code like "cryozonic_%";
    DELETE FROM eav_attribute_group WHERE attribute_group_code like "stripe-%";
    DROP TABLE cryozonic_stripe_customers;
    DELETE FROM setup_module WHERE module = 'Cryozonic_StripeSubscriptions';

Upgrade

You can always download the latest version of the module from the account section or through the email that was sent to you when you purchased the module. Once you have the latest version, and

How to enable and configure

The Stripe Subscriptions add-on will inherit its configuration from the core Stripe Payments module. Please see the Stripe Payments configuration instructions before enabling Stripe Subscriptions.

Once the core Stripe Payments module is configured, subscriptions for any Magento product can be enabled very simply 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.
  • Billing Interval: Can be Days, Weeks, Months or Years. Whatever you choose here will be displayed to the customer in the front end, so if you prefer to display "30 Days" instead of "1 Month", set this to Days instead. If Days are specified, the subscription will also be created in Days in your Stripe account.
  • Billing Interval Count: How often the billing should occur, so if you specify 30 here, a billing event will occur every 30 Days or whatever unit you chose in the previous setting.
  • Trial Days: The amount of days before the first charge for the subscription.

You do not need to do anything else, like creating a subscription plan in your Stripe account. An appropriate subscription plan will automatically be created for this product when your customers checkout. For more details, see the next section.

How subscriptions are created in your Stripe account

When a customer places an order, a subscription plan is created in your Stripe account in a way that the product price, tax and ordered Qty are used in the subscription plan price. Here is an example of how subscription plans will be created in your Stripe account:

Notes on the above:

  1. The product name at the time of the purchase is used as the plan's name.
  2. If another customer purchases the exact same product, Qty and has similar price and tax, then no new plan will be created. That customer will be subscribed to the already existing plan for that product.
  3. You will notice that the newly created subscriptions to these plans will have a Trial status. This is because a payment has already been taken for the entire purchase during the checkout. This is done so that if the customer purchases a regular product together with a subscription, they will only see a single transaction in their bank statement for their order. If the subscription billed the customer separately, this may cause confusion to them as they wont be able to match the amount to the order from your website.

When you click on a subscription to view it, you will notice that a lot of Metadata are saved on the subscription as shown in the below screenshot:

These metadata are used for both informational and functional purposes, so don't delete any of them.

To change the shipping address of a subscription, you can edit the subscription's Shipping metadata shown above.

How can customers view, cancel and edit subscriptions

When customers navigate to their account, they can view their purchased subscriptions by clicking the «My Subscriptions» link on the sidebar:

Customers can view or cancel their subscriptions from here, as well as edit their shipping address. The displayed shipping address is not the same as the customer's address in Magento. The customer's Magento shipping address is used during the checkout and saved on the subscription's metadata as shown in the previous section. When a customer edits the shipping address from this section, only the metadata is updated on the actual subscription. The customer's Magento shipping address will remain the same.

How can admins edit subscriptions

You have seen from the previous section what customers can see in their account about their subscriptions. All of that information is pulled directly from the Stripe API, i.e. nothing is saved on your own server about the customer's subscription. What this means for admins is that whatever changes are made to a subscription from the Stripe dashboard, they will automatically be reflected into the customer's account section:

The following things can be edited from your Stripe dashboard:

  • Rename the subscription plan
  • Cancel customer subscriptions
  • Apply discount coupons
  • Add, change or remove trial periods
  • Edit the shipping address through the subscription's metadata

For switching customers from one subscription plan to another, please see this section.

How to create recurring subscription invoices using Stripe Webhooks

When you create a monthly subscription for a customer, then Stripe will issue an invoice every month which is automatically paid in your Stripe account. Stripe Payments & Subscriptions can receive notifications from Stripe that an invoice has been created, and it will automatically create the same invoice against the original order in your Magento admin area. Merchants can navigate to the Invoices section of that specific order to view all payments received for that specific order:

Merchants can also view all generated invoices for all orders by navigating to Sales > Invoices. Once the invoice has been generated, customers will be able to view and download their invoices when they log into their Magento customer account.

The method used for generating these invoices is an events notification system called Stripe Webhooks. When Stripe Webhooks are configured, Stripe will send a notification to your web server every time an invoice is generated and a payment is processed for the customer's subscription. To configure Stripe Webhooks, navigate to https://dashboard.stripe.com/account/webhooks and add the following endpoint URLs for your Test and Live modes:

http://yourdomain.com/cryozonic-stripe/webhooks

Once added, your Stripe account should look like the following:

Please note: As of Stripe Payments v1.6.0, there is a single webhooks configuration endpoint for all add-ons, which can handle all event types and which replaces all older webhook configurations. Please see Stripe Webhooks Configuration for details on how to set this up.

Recurring billing notifications

If you would like your customers to receive email notifications when a recurring billing event occurs, you will need to do the following:

  1. From Stores > Configuration > Sales > Payment Methods > Stripe Payments - set the «Email Stripe email receipts» configuration option to Yes
  2. From your Stripe dashboard, enable email receipts from https://dashboard.stripe.com/account/emails
  3. Customize your email receipts from https://dashboard.stripe.com/account/public

Creating subscription orders from the admin area

In Magento 1, where recurring profiles are used to enable subscriptions, merchants cannot create subscription orders from the admin area. However, with our Magento 2 Stripe module, merchants can now add subscription products to any order they create from the admin area:

There absolutely no limitations compared to how Magento 1 works, so feel free to add subscription products to orders just like other regular products.

Switching customers from one subscription to another

The recommended method of switching a customer from one subscription to another is from the Magento admin area. Although you can also switch customers to different subscriptions from the Stripe dashboard, if you do so, you'll get the following side effects:

  • The metadata that are saved against a subscription will not be updated.
  • The customer wont be able to find the original order number that was used to create the subscription from their account's My Subscriptions tab.
  • If you have configured recurring invoicing using Stripe Webhooks, these will no longer be created and the Stripe Webhooks events will no longer work for those subscriptions.
  • Your customer will not receive an updated order email that breaks down the itemized billing.

Because of the above issues, a better way to switch a customer from one subscription to another is to create a new order from the admin area. At the payment method section, the following options will be presented to the merchant:

In the above screenshot, all of the customer's active subscriptions will be loaded from the Stripe API. You can select the one you want to cancel before creating the new subscription. In the dropdown, you will see the subscription name, the recurring billing amount, as well as the date at which the next payment will be attempted. This billing date is used to automatically pre-populate the following date field which will be used to set a trial for the subscription. The subscription trial will end on the date in this date field.

No payment details are necessary for switching subscriptions. The customer's default card (which will normally be the same as the one used for the existing subscription) will be used to create the new subscription. If for any reason the customer needs to use a new card, you can update that from https://dashboard.stripe.com/customers.

If you don't see the above subscription switching options in the admin, make sure to only have a single subscription product in this order.

Creating a configurable subscription

Two examples of configurable subscriptions can be found on the demo server. These two products have been created in Magento as Configurable Products which have both Customizable Options and Configurations under each of their product pages.

Customizable Options are used when you need to offer different prices of the same product, i.e. in the Coffee Beans example, this is the "Bag Size" customization which will increase the subscription price if a larger bag is selected.

Configurations are used when you need to offer subscriptions of different billing intervals to the customer, i.e. this is the Dropdown and Text Swatch controls that allow the customer to select between One-off, Monthly or Quarterly subscriptions.

You can review how these products have been configured at the admin area:

In the above example, each subscription is enabled and configured on each of the Simple Products (these are created automatically by Magento). The configurable products (which you create manually) is where the simple products are grouped together through Configurations.

To create a configurable product similar to the above:

  1. Create a new product from the Catalog (it can be of simple or virtual type)
  2. Scroll down and find the Configurations tab

  3. Create a new configuration. The following screen will appear:

  4. Create a new attribute called "subscription" and make sure it is "Global" under the "Advanced Attribute Properties" tab (example). You can also select here whether you would like this attribute to be a Dropdown or a Text Swatch (example).
  5. Make the attribute required
  6. Under "Manage Options", add the values that will appear in the dropdown or text swatch. For text swatches, there will be an additional column called "Swatch" which must be completed.

  7. Under the "Manage Labels" tab, add whatever you would like to show to the customer on the product page, i.e. "Subscribe and save 5%"
  8. If you are configuring the attribute as a Text Swatch, you can optionally enable "Used in product listing" under advanced attribute properties in order to make it appear in the catalog similarly to the demo server
  9. Save the attribute. It should now appear in the attributes list where you can select it and press the "Next" button
  10. Select all of the attribute values on the next page and complete the steps until you are back on the product page

  11. Magento will then create 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
  12. Navigate back to the products catalog and select each of the newly created subscription products
  13. Make sure that the Subscription attribute of each product has the correct value:

  14. Enable and configure each product's subscription from the Stripe Subscriptions tab

Shipping for subscriptions

Newly created subscriptions will include the shipping cost of the order in the initial payment, but exclude it from all recurring payments. The reason for this is that with the Magento 2 shipping methods, the shipping cost is calculated per order, not per cart item. Magento 2 does not provide a breakdown of shipping costs for each item row on an order. There is no way of calculating the shipping cost of a specific item in an order because the shipping cost calculation is performed inside the module of the shipping method that the customer selected during the checkout, and is performed for the entire order.

The merchant has a number of options to deal with this:

  1. Use a free shipping method for subscriptions, but include a fixed shipping cost in the subscription price (this method is explained below).
  2. Configure similar subscription products with different fixed shipping prices, which are made available only to specific countries / stores / shipping addresses.
  3. Simply offer all subscription products with "Free Shipping" so that customers have an incentive to buy a subscription instead of buying the product individually.
  4. Charge the shipping cost separately from your Stripe account when a subscription item is shipped.

In the case that a subscription is created as a Virtual Product, then Magento will not ask for a shipping address from the customer. This means that shipping will be free for the subscription.

However when a subscription is created as a Simple Product, then a shipping address will be collected and if you have a shipping module configured, it may calculate a shipping cost for a subscription, which will only be charged at the initial checkout session but not in subsequent subscription cycles. If you would like to exclude this shipping cost from the initial order completely, you can create a promotion rule from:

Marketing > Promotions > Cart Price Rules > Add New Rule

Under the "Actions" tab, select Free Shipping for matching items only:

Under "Apply the rule only to cart items matching the following conditions", create a rule based on the Subscription Enabled attribute

Translations for multi-language websites

The module contains a translations file that can be used with multi-language Magento configurations. You can find this file under:

app/code/community/Cryozonic/StripePayments/i18n/en_US.csv

To create a translation file for a different language, you can copy the file under:

app/code/community/Cryozonic/StripePayments/i18n/languagecode_COUNTRYCODE.csv

Make sure to replace languagecode_COUNTRYCODE with the locale code of the target locale language. This would be the same language that you selected under System > Configuration > General > General > Locale Options > Locale. If you must set your Locale configuration for the first time, make sure to also flush your Configuration Cache after doing so.

Once you have copied the file, you can simply edit the file and replace the second string on each row with the translation of the first string. There is nothing else you need to do for translations.

Migration from Magento 1 to Magento 2

The migration of Stripe Subscriptions to Magento 2 is similar to the migration of Stripe Payments, with the following additional steps:

  1. Before running the data migration, add the following to your class-map.xml.dist:
                <rename>
                    <from>cryozonic_stripesubscriptions/source_configurable</from>
                    <to></to>
                </rename>
  2. Manually migrate the sales_recurring_profile table in the Magento 2 database with the following commands:
    mysqldump -u root sourceDatabase sales_recurring_profile sales_recurring_profile_order > sales_recurring_profile.sql
    mysql -u root destinationDatabase < sales_recurring_profile.sql
  3. Run the migration using the Data Migration Tool.
  4. After the data migration has finished, find one of the old subscription products, and ensure it has the "Migrate_Recurring Profile" attribute group as shown below:

  5. From your command line, run the following commands:
    php bin/magento cryozonic:stripe-subscriptions:migrate-attributes
    php bin/magento cryozonic:stripe-subscriptions:migrate-products-configuration

    This will add the correct attribute groups to each migrated attribute set, and will also migrate the configuration from the old Recurring Profile section, to the new Stripe Subscriptions section.

  6. Find your Stripe Secret API key from https://dashboard.stripe.com/account/apikeys
  7. Run the following command:
    php bin/magento cryozonic:stripe-subscriptions:migrate-stripe-subscriptions <your Stripe Secret API key>

    This will perform the API calls to Stripe which will modify old subscriptions to work with the Magento 2 module. The API calls will essentialy update the existing subscriptions with additional metadata used by the Magento 2 version of the module.

  8. To finish things off, make sure that you also update your webhooks endpoint, which is different from the Magento 1 format (it has a dash instead of an underscore)

There are some important differences with the Magento 2 version of the module which you must be aware of:

  1. There is no longer the notion of recurring orders. Every time a subscription is billed, a new invoice is generated against the original order.
  2. Initial fees are not supported yet, and thus will not be migrated.
  3. Newly created subscriptions do not have the tax_percent parameter. The tax is included in the subscription price. The tax_percent parameter will be supported in the future.
  4. During the migration, the shipping address for each migrated subscription will be set to the shipping address that was used in the original order, which is retrieved from the sales_recurring_profile.

For full configuration instructions, please see our online documentation at http://store.cryozonic.com/documentation/magento-2-stripe-subscriptions

Troubleshooting

Generic troubleshooting of the module

Please see the Stripe Payments troubleshooting documentation.

Subscriptions are trialing even though they have no configured trial period

This is by design in the module. The reason that the module works this way is so that when a new order is placed, if the order includes several regular products mixed with several subscription products, then the intention is for the customer to see only a single charge on their bank statement. So instead of creating each subscription individually through the Stripe API (thus resulting in multiple charges), the module creates a single charge for the entire initial order, and then sets up all subscriptions separately. When the subscriptions are set up, they are automatically assigned a trial period equivalent to the duration of the subscription frequency. If a trial period exists in the product configuration, this is added on top.

Once the separate subscriptions are set up, the customer will then get billed individually for each of those. So if they bought a monthly subscription and a weekly subscription, they will start seeing the weekly charges and the monthly charges separately on their bank statement. They will also be able to cancel any of those individually from their account section, even though they placed a single order for both subscriptions.

Please note that the underlying trial implementation is completely transparent to the customer. When the customer views the customer configuration section, they will see the subscription as active. They will only see a trialing subscription if a trial period has been configured for that product.

Customer Support

If you have any other issues installing, configuring or using the module, please contact us at info@cryozonic.com