Stripe Subscriptions - Magento 1 - Documentation

  1. About
  2. Installation
    1. Recommended Method
    2. Manual Installation
    3. Uninstalling
    4. Upgrading
  3. Configuration
  4. How subscriptions work
  5. Creating a subscription plan
  6. Setting up recurring orders with Stripe Webhooks
  7. Creating a configurable subscription
  8. Reviewing and updating customer subscriptions
  9. How pausing and resuming subscriptions works
  10. Adding or updating subscription plans
  11. Discount Coupons
    1. Overview
    2. Important Configuration Settings
      1. Coupons Configuration
      2. Tax Settings Configuration
    3. Other Considerations
  12. Creating subscription orders from the admin area (Mail/Telephone Orders or MOTO)
  13. How to change the shipping address for a subscription
  14. Translations for multi-language websites
  15. Troubleshooting
    1. Enable Error Logging
    2. Front-End Crash (Website does not load)
    3. Continue to Next Step button does not work (stuck spinner)
    4. Continue to Next Step button redirects to the shopping cart
    5. Broken Admin Area
    6. Failed/Partial/Corrupted Installations
    7. Nominal item can be purchased standalone only.
    8. No Shipping Methods Available
    9. Missing Grand Total for subscriptions
    10. Missing Pause/Cancel Buttons
  16. Thanks

About

Stripe Payments is a module for Magento 1 which allows merchants to accept payments using the Stripe payment gateway. Stripe Subscriptions is an optional add-on module to Stripe Payments which extends its functionality to allow merchants sell subscriptions using the Stripe payment gateway. For Stripe Subscriptions to work correctly, both modules must be installed. This is the documentation for installing, configuring and using Stripe Subscriptions on Magento 1. For the Stripe Payments documentation, please click here.

Installation

Stripe Subscriptions is an add-on to the Stripe Payments module. This means that both modules must be installed for the subscriptions to work. For the latest version of Stripe Subscriptions, please make sure that you also have the latest version of Stripe Payments installed before installing the subscriptions add-on.

The installation procedure is similar to Stripe Payments:

  1. Make sure you have downloaded the module from your customer account section or through the email that was sent to you when you purchased the module.
  2. Log into your website's magento admin section.
  3. Make sure that compilation is disabled from System > Tools > Compilation.
  4. Go to System > Magento Connect > Magento Connect Manager and log in.
  5. Under «Direct package file upload», upload the .tgz file that you downloaded from our website.
  6. Click the «Install» button when the module has uploaded successfully. Check the black console to make sure that there were no errors.

    Magento Stripe Subscriptions Install

  7. If you had compilation enabled, re-compile from System > Tools > Compilation.

Both modules should now appear in the modules list as shown in the screenshot. You are now ready to create your first subscriptions plan.

Manual Installation

If for any reason the above procedure did not work (usually because the web server has no write permissions in your Magento directory), then you can install the module manually by simply extracting the module in your Magento's root directory.

  • Double click the .tgz file to uncompress it. If you are on a version of Windows that does not support this, we recommend using the 7-Zip file archiver to uncompress the module.
  • Upload the extracted files by FTP to your website, inside your website's root Magento directory. If you do not have an FTP client already, you can use FileZilla.
  • A single page refresh of your website will set up the module and its database dependencies.
  • Flush your site's caches, merged CSS and Javascript, and re-run compilation if necessary.
  • You can now configure the module.

Uninstalling

If you have installed the module from Magento Connect Manager, it should be just as simple to uninstall through the same interface as shown in the following screenshot:

Magento Stripe Subscriptions Uninstall

If you have installed the module manually, please refer to the Troubleshooting section for manual uninstall instructions.

Upgrading

Before upgrading Stripe Subscriptions, you must make sure that you are using the latest version of Stripe Payments, the base module on which Stripe Subscriptions depends. Upgrade instructions for Stripe Payments can be found here.

Once you have upgraded Stripe Payments, you can then download the latest version of Stripe Subscriptions from your account. To upgrade the module, simply uninstall and re-install the module using these instructions.

Configuration

Stripe Subscriptions uses the same configuration options from Stripe Payments. In addition to those options, you can find another Stripe Subscriptions configuration section under Payment Methods as shown in the screenshot below:

Magento Stripe Subscriptions Configuration

  1. Subscription Group and Cancelled Subscription Group - These options allow you to automatically assign or un-assign users from specific customer groups when they buy or cancel a subscription. The same groups will be used when they pause or resume a subscription.
  2. Failed Payments Group – This group will be used when a «invoice.payment_failed» event is sent by Stripe to us using their Webhooks feature. If you plan on using this group, please make sure that you have configured Webhooks correctly according to the instructions in the «Other necessary configuration» section. This feature can be used in combination with Magento rules to allow access to specific sections of the website, apply discounts for subscriber and anything else you can do with Magento rules. If you have configured Webhooks, then Stripe Subscriptions will also be able to handle «invoice.payment_succeeded» events coming from Stripe. When one such event is received, an order is re-created based on the original customer subscription at the time the event is sent. This new order can be viewed under Sales > Orders and will have an order status depending on the value of «Recurring Order Status» in the configuration.
  3. Invoice Orders – Choose whether to create an invoice for a new or recurring order automatically. If set to Manually, the admin has to manually issue the invoice from the admin area, which may be useful if the merchant does not want to create an invoice unless the order items have shipped. Do not confuse this option with the «Authorize Only» option in the Stripe Payments module – if an invoice is not created for a subscription order, it does not mean that the payment has not been received. Stripe will charge the customer normally based on the subscription's billing cycle. The invoice in Magento will not be associated with when the actual payment took place. The same goes for refunding these invoices – a subscription refund will always be offline and will not refund the actual payment from the Stripe account.
  4. New & Recurring Order Status – Both new and recurring orders will have the status that is configured from this field.
  5. Send Recurring Emails – If this option is enabled, then a customer email will be sent for the newly created order after a recurring billing event has occurred.
  6. Pause/Resume Subscriptions – Enable this if you would like your customers to be able to pause or resume a subscription which they have purchased. More information about how this works can be found on page 26 under the section «How pausing and resuming subscriptions works».
  7. Hide grand total when zero - If a user purchases a subscription on its own (i.e. with no regular products in the cart), then Magento will display a «Grand Total» of zero in the shopping cart and the checkout page. This is because the Grand Total only applies to regular products. Enable this option to let Stripe Subscriptions override Magento to hide the Grand Total if it is zero, as shown in the screenshot below:

    Magento Stripe Subscriptions Hide Grand Total

  8. Configurable Products Input – If a subscription is created as a configurable product, then the customer can select the option they like from either a dropdown, radio box or a checkbox as demonstrated at http://demo.cryozonic.com/subscriptions/coffee-beans.html. Each product will have its own Stripe Subscriptions tab in the product configuration page from where this setting can be set. If a product-level setting is not set, then this global setting in the module configuration will be used instead.

How subscriptions work

When your customers purchase a subscription from your website, the module sets up the subscription in your Stripe account so that the customer is billed automatically by Stripe at the end of each cycle. The subscriptions in your Stripe account will look like the following:

Even when the customer renews their card with their bank, Stripe can still continue using the same renewed card without any necessary update by the customer or the merchant.

When a customer is billed, Stripe notifies your website using our module's integrated webhooks system, so that new orders are automatically created in your admin area and in the customer account section. The customer can also receive either a new order email or a Stripe email receipt depending on how the module is configured.

Subscriptions can be created for both physical products as well as for virtual services. The difference is that during the checkout process, physical products will ask the user for a shipping address and a shipping method. Virtual products on the other hand will go straight from the billing address to the payment method and then the order review. An example of a virtual product checkout is shown in the screenshot below:

Magento Stripe Payments How

When a product like this is purchased from your website, the Stripe Subscriptions module will set up the customer profile and the subscription plan on Stripe's servers, without ever redirecting the customer away from your website. The entire process happens in the background between your server and the Stripe API (or Stripe.js API when Stripe.js is enabled).

Once a subscription has been set up, a payment is taken immediately unless a trial period has been set. If there is a trial period, the first payment is taken the day that the trial expires.

The subscription can be canceled from 3 different locations:

  • by the user through their Magento account
  • by the Magento administrator through the admin area
  • by the Stripe account holder through the Stripe dashboard

A configured subscription will look like so in Stripe's dashboard:

Magento Stripe Subscriptions Dashboard

Creating a subscription plan

To create a subscription plan:

  1. Go to Catalog > Manage Products
  2. Click the «Add Product» button
  3. For the product type, select «Simple Product» if you need to collect shipping details, or «Virtual Product» if you do not need a shipping address or shipping method. These are the only two types of products that can have a recurring profile, however you can associate simple and virtual products with bundled, grouped or configurable products.
  4. Under the General set the Tax Class to what you like. The module will add any variable fees such as tax and shipping into the final Stripe subscription plan price, which is automatically created for you during the customer checkout. This means that the module may create multiple Stripe subscription plans for every Magento recurring product that you create.
  5. Click the "Subscription" tab from the sidebar (translated from "Recurring Profile")

    Magento Recurring Profile Configuration

  6. Enable the subscription and fill in each section as follows:
    1. Schedule: Do not change; leave everything to their default value.
    2. Billing: Set the billing period to day, week, month or year. Stripe does not support half-months. If you want to charge your customers every month, set the Billing Period Unit to «month» and the Billing Period Frequency to «1». Leave the maximum billing cycles empty.
    3. Trial Period: Stripe only supports days when setting a trial period, but the module will attempt to convert the input from here into days based on the values of Trial Period Unit and Trial Billing Frequency. The remaining 2 fields are ignored by the module; however Magento requires them to be set in order to allow the customer to buy the subscription. Set the Maximum Trial Billing Cycles to 1 and the Trial Billing Amount to 0.
    4. Initial Fee: If you have any initial/setup costs, you can set these here. The module will make sure that these are added in the very first payment from the user as soon as the subscription is set up.
  7. If you have created a virtual product, don't forget to disable stock management under the Inventory tab. You may also want to set the Maximum Qty Allowed in Shopping Cart to 1, unless it makes sense for the customer to buy the same subscription in multiple quantities. If this is the case, then the Qty in the shopping cart will be taken into consideration by the module when setting up the subscription.
  8. Fill all other product options in any way you like and save the product.

Once the product has been created, test a purchase on your website and make sure that a subscription plan has been created in your Stripe dashboard. An order will also have been created under Sales > Orders. This order can re-occur for every billing period when you configure Stripe Webhooks as explained in the next section.

Setting up recurring orders with Stripe Webhooks

Some 3rd party subscription modules implement subscriptions by requiring the setup of a cron job to create charges manually on a recurring basis. Stripe Subscriptions does not follow this approach - it instead uses Stripe's native subscription features. This means that once the customer signs up to a subscription plan, it is up to Stripe to continue charging the customer's card for every billing period.

But how would a merchant know that a recurring billing event has succeeded or failed so that an order can be fulfilled? Stripe provides an event emission mechanism called Stripe Webhooks which can notify the merchant's website about a billing event. When a successful billing event occurs, Stripe emits an invoice.payment_succeeded event, whereas when a payment fails, Stripe emits an invoice.payment_failed event. Both of these events can be received by Stripe Subscriptions on the merchant's website and be acted upon in the following way:

  • invoice.payment_succeeded – When this event occurs, Stripe Subscriptions has an advanced feature which will find the original order of the customer and re-create it using the same order items, tax information, shipping details and coupons. If the subscription product has any initial fees configured, these will be removed from the recurring order. Furthermore, if the customer used a coupon and Stripe did not discount the billing amount for this period (i.e. because the coupon has expired), then the discount will also be removed from the recurring order. Stripe Subscriptions will automatically invoice the order offline (because the payment has succeeded) but will not mark the order as shipped. The merchant can then view this order as any other regular order coming into their website and fulfill it accordingly. If the merchant desires to mark recurring orders into a particular order state when they are created, then Stripe Subscriptions will respect a configuration setting called «Recurring Order Status» and will mark the order as the merchant wishes. If this setting is not set, then the order will be marked as complete. Finally, if configured, the module can also send a recurring order email to the customer similar to the original email that they received the first time that they have placed their order.
  • invoice.payment_failed – Stripe is very good at trying to avoid failed payments by automatically updating expired cards with the customer's bank instead of requiring the customer to enter new card details manually. However, payments may still fail if for example the customer's bank account has run out of funds. When this event is received by Stripe Subscriptions, then the module will move the customer into a «Failed Payments Group» that is configured from the module's configuration section. No order will be created in the Magento admin area for this customer. It is up to the merchant to periodically check if any customers have been moved to the failed payments group and act according to the business needs.
  • customer.subscription.deleted – Merchants can configure their Stripe account to cancel a subscription after a certain amount of payment failed attempts. If a subscription is cancelled because of this, then this event will be sent to the module and the recurring profile in Magento will be cancelled as well. This event will not affect the customer group.

Stripe Subscription sets up the following endpoint to accept Stripe Webhooks events:

http://yourdomain.com/cryozonic_stripesubscriptions/webhooks

To connect Stripe with your Magento setup, go to your Stripe dashboard and under API > Webhooks, add the above endpoint as shown in the following screenshot:

Magento Stripe Subscriptions Webhooks

When adding the webhook endpoint, make sure to only select the three events:

  • invoice.payment_succeeded
  • invoice.payment_failed
  • customer.subscription.deleted

If you add an endpoint for testing purposes, don't forget to also add the same endpoint for your live mode. For more information about Stripe Webhooks, please refer to https://stripe.com/docs/webhooks

DEVELOPERS TIP – If your website is not live yet and you would like to test the Stripe webhooks, you can simulate a Stripe webhook request using the following steps:

  1. First place a subscription order on your website. Note the subscription ID, e.g. sub_7CoQ8Xn4Kp9REq for later use.
  2. In your Stripe dashboard, configure the test webhook URL to a http://requestb.in/ endpoint.
  3. Send a test webhook event from your Stripe dashboard and capture the request body from requestb.in. Save that request body for later use.
  4. Using the Chrome Postman extension, create a POST request to http://yourdomain.com/cryozonic_stripesubscriptions/webhooks with a request body that is the same as the one you captured earlier.
  5. Modify the subscription ID in the request body to be the same as the subscription ID of your placed order, e.g. sub_7CoQ8Xn4Kp9REq.
  6. Trigger the request from Postman and check if a new order was created under Sales > Orders.

Creating a configurable subscription

The simplest way to create configurable subscriptions is to use the Custom Product Options tab under your product's configuration page:

Magento Stripe Subscriptions Configurable

This will allow your customers to customize the product (and the subscription price) before adding it to their cart.

Custom Product Options are suitable if you need to only adjust the price of the subscription. If you would like your customers to be able to adjust the billing frequency of the subscription (i.e. monthly, weekly etc), then you need to follow a different approach involving Magento's configurable products.

To achieve configurable billing frequencies, you must first create a «subscription» attribute that will be used by the configurable product. You can do this from Catalog > Attributes > Manage Attributes. An example of how to set up this attribute can be viewed on the demo server on this page. You can set the labels of the attribute to whatever you want your customer to see on the product page as shown in the following screenshot:

Magento Stripe Subscriptions Configurable

Save the attribute and add it to your Default attribute set from Catalog > Attributes > Manage Attribute Sets.

Then create a simple or virtual product for each one of the labels that you specified above, and set the recurring profile billing cycle to match the labels that you have chosen. You can see how we created the Coffee Beans subscription on our demo server by inspecting the configuration of its associated simple products in the product catalog.

For each simple product that you create, make sure to set the Subscription attribute accordingly:

Magento Stripe Subscriptions Configurable

Then, create a master configurable product, which will be associated with all the simple products. When you create this configurable product, choose the «Subscription» attribute that you created as the common denominator:

Magento Stripe Subscriptions Configurable

When you are done setting up the master configurable product, go to it's Associated Products tab and select all the simple products that you need to associate with it:

Magento Stripe Subscriptions Configurable

Finally, depending on how you would like the customers to select the billing frequency from the product page, go to the Stripe Subscriptions tab and select one of Dropdown/Radio Buttons/Checkbox:

Magento Stripe Subscriptions Configurable

This setting is specific to each individual subscription product that you create and overrides the global setting, which can be set from the module's configuration section:

Magento Stripe Subscriptions Configurable

Reviewing and updating customer subscriptions

Once a customer has purchased a subscription, they can review their plan from their account as shown in the following screenshot:

Magento Stripe Subscriptions Review

The customer can cancel, pause or resume a subscription by clicking on one of the recurring profiles and then updating its state using the top right hand buttons:

Magento Stripe Subscriptions Review

Subscriptions can also be reviewed and updated from the Magento admin area. To find all of the subscriptions, just navigate to Sales > Recurring Profiles. From here, you can cancel/pause/resume any subscription in the same manner as your customers can.

Magento Stripe Subscriptions Review

How pausing and resuming subscriptions works

Customers can view their purchased subscriptions by logging into their customer account section:

Magento Stripe Subscriptions Pause

Once there, your customers can cancel the subscription, pause or resume (suspend or activate), or view the related order for that subscription.

The subscription ID is the same that is used in your Stripe dashboard. Under the «Subscription Schedule», your customer can view when their subscription started and based on the billing period, estimate when the next payment will happen.

With Stripe Subscriptions, when a subscription is paused or resumed, a full unsubscribe and re-subscribe to the subscription plan is happening behind the scenes. This is in accordance with Stripe's official recommendations. When the customer is re-subscribed, the module moves the next billing period into the future by adding trial days on the subscription. For example, consider the scenario where you have a 1 month subscription and your customer subscribed on the 10th of January to that subscription. The next billing date would normally be on the 10th of February. If your customer decided to pause the subscription at any time for 5 consecutive days and then resume it, then when they resume, their next billing date will be on the 15th of February. No payment will be charged until the 15th of February.

If the same subscription product had any trial days set, then the trial days would also be shifted in the same way and you will receive the very first payment at the end of the shifted trial days.

Furthermore, when the customer resumes the subscription, the «Start Date» field under the «Subscription Schedule» section will be updated to be their next billing date (i.e. 15th of February in the above example). This is to prevent customer confusion about when their next billing date is.

Hiding or renaming the Suspend/Activate buttons

Please note that if you disable pausing/resuming subscriptions from the module's configuration section, then the module will not hide the default Suspend/Activate buttons. This is left to your theme and can easily be done with either CSS or template editing.

If this feature is disabled but the buttons are not hidden, then the customer will receive a warning when they try to suspend the subscription:

Magento Stripe Subscriptions Hiding

If you would like to rename the labels of these buttons to Pause/Resume, you can do so by editing the module's locale files under app/locale/en_US/Cryozonic_StripeSubscriptions.csv. Simply add the following two lines at the end of the file:

"Suspend","Pause"
"Activate","Resume"

Adding or updating subscription plans

When you create a new plan, you should be aware that the plan is only created in your Magento store, not on Stripe. When the customer checks out with that plan in their cart, the module automatically creates the plan if it doesn't already exist. Notice how in your Stripe dashboard plans have IDs in the following format:

Magento Stripe Subscriptions Updating

This example plan ID is comprised of the following elements:

  • 167 – The product ID in your Magento store that has a recurring profile.
  • GBP – The currency code of your store.
  • 900 – The amount in cents/pence, i.e. £9.00
  • MONTH – The billing period unit
  • 1 – The billing frequency, i.e. every 1 month

This means that if you change any of the above values when updating a product with a recurring profile, a new plan will be created with a different ID. The reason for this is that Stripe does not allow plan modifications for anything other than the plan's name. It also means that customers who are already subscribed to a plan do not get affected if you decide to change something on the plan from your website.

If there are any variable fees such as taxation, shipping cost or qtys during the checkout, these will be added to the total amount, so multiple Stripe plans may be created for each magento recurring product depending on the checkout amount.

Discount Coupons

Overview

Stripe Subscriptions implements coupons for subscriptions, however there are some differences between Magento coupons and Stripe coupons which you must be aware of.

Stripe's coupons only support the following basic features:

  1. Discounts by percentage of total value.
  2. Discounts by a fixed amount on total value.
  3. Expiration after a certain amount of time.
  4. Expiration after a certain amount of redemptions.
  5. Expiration at a specific date.

On the other hand, Magento can have very flexible rules on coupons and discounts, which are not supported by Stripe. You can explore all the different options by creating a Magento coupon under Promotions > Shopping Cart Price Rules.

The coupons implementation by Stripe Subscriptions works by matching the Magento coupon Code with the Stripe coupon ID when a subscription order is placed. If a coupon exists in Stripe with the same ID as the Magento coupon code, then the Stripe coupon is added on the user's subscription, which means that the customer will receive a recurring discount until that coupon expires.

Important Configuration Settings

Please review the following important configuration settings in order to set up coupons correctly:

Coupons Configuration

The following settings are set on the discount coupon under Promotions > Shopping Cart Price Rules

  1. The Magento coupon code is case-sensitive and must exist in both your live and test modes in Stripe:

    Magento Stripe Subscriptions Discount Coupon Code

    If a coupon is deleted from your Stripe account and a customer tries to use it, it will be silently ignored. It is up to you to keep the Stripe coupon IDs and the Magento coupon Codes in sync.

  2. Under the "Actions" tab, you must set the «Apply» and «Discount Amount» fields to match the Stripe coupon discount. "Apply" can only be a percent or a fixed amount.

    Magento Stripe Subscriptions Discount Coupons

  3. Fixed amount discounts must have the setting “Maximum Qty Discount is Applied To” set to 1.

    This is necessary in order to match Stripe’s discount calculation algorithm for fixed amounts. For example, when a customer buys 2 boxes of chocolate at $10 each, and applies a $5 discount voucher, then Stripe’s total subscription price will be $15 ((2 x $10) - $5). If this setting is not set in Magento, then Magento's discount algorithm will be (2 x ($10 - $5)) which will result in a wrong price of $10.

  4. Percent discounts must have the setting “Apply to Shipping Amount” set to Yes.

    This is necessary because the Stripe API does not have a parameter for setting the shipping cost, so the product price and the shipping cost are combined together in the subscription price. Then, Stripe will bill the customer using the following formula:

    (product_price + shipping) * (1 - discount_percent) * (1 + tax_percent)

    To match Stripe's formula, the discount must be applied on the shipping cost too.

Tax Settings Configuration

The following tax settings are under System > Configuration > Sales > Tax

  1. If your subscriptions have shipping costs, then shipping must be included in the tax calculation algorithm:

    This is necessary because Stripe does not have a separate shipping price field for subscriptions. So when a subscription is created, the product price and the shipping price are combined to create the final subscription price. Stripe’s tax calculation algorithm is:

    (product_price + shipping) * (1 - discount_percent) * (1 + tax_percent)

    To match Stripe's formula, the shipping cost must be included in the tax calculations. If you don’t want to apply tax on shipping for regular products, then simply include all subscription shipping costs in the product price and leave this setting to None.

  2. Magento must be configured to use the Total tax calculation algorithm:

    This means that tax is calculated based on the “row total” for each subscription order, i.e. after the discounts have been applied. The module also overwrites the algorithm to include the shipping amount in the subscription price. If a different method is selected, the custom algorithm will not have any effect and will result in wrong totals in Magento.

  3. Magento must also be configured to apply the tax after the discount, to match Stripe’s algorithm:

  4. Weee Taxes are no longer supported from version 1.9.0 onwards, which passes a tax_percent to Stripe rather than adding the tax amounts in the subscription price. If you don’t know what a Weee tax is, then you do not need to do anything as Magento does not calculate these by default.

Other Considerations

  1. If you are using "initial fees" with percent discounts, then the initial fee will be discounted as well. This is because Stripe applies percent discounts on the entire Stripe invoice amount, which includes the initial fees.
  2. Initial fees are always removed from recurring orders.
  3. Expired discount coupons are also removed from recurring orders.
  4. The coupons implementation will also work with a mixture of regular products and subscriptions as shown in the following screenshot:

    Magento Stripe Subscriptions Discount Coupons

Creating subscription orders from the admin area (Mail/Telephone Orders or MOTO)

Magento normally treats a subscription (or recurring profile) as an item that needs to be purchased on its own (i.e. it must be the only item in the customer's shopping cart). This is so that the customer is able to cancel or pause/resume individual subscriptions from their account without canceling an entire order's subscriptions.

To convenience your customers, Stripe Subscriptions 1.5+ adds functionality to Magento that allows your customers to place orders that contain both subscription products and regular products. To achieve this, the order is split into multiple orders in the admin area to comply with Magento's core features. If for example the order contains 2 subscription products and 2 regular products, then the order will be split into 3 orders in the admin area – one for each subscription and one with the other 2 regular products.

In addition to the above, up until the latest version of Magento 1.9.x, creating orders from the admin area that contained products with recurring profiles was not fully supported. Magento doesn't have a «Create Recurring Profile» button in the «Recurring Profiles (beta)» section. Stripe Subscriptions v1.6+ adds extra functionality that allows you to create orders with subscription products and allows admins to successfully capture the payments from the Magento admin area.

Magento Stripe Subscriptions Admin

Creating subscriptions from the admin area is similar with the order splitting that the customer experiences in the front-end, i.e. subscription products must be purchased on their own. However there is no order splitting in the admin area. The admin is responsible for creating the subscription orders separately from the regular product orders. If the admin attempts to add both subscription products as well as regular products in a new admin area order, then they will receive an error notice.

How to change the shipping address for a subscription

If a customer changes their billing or shipping address from their customer account section, this change will not be reflected on their existing subscription orders.

When a recurring order is created, the shipping address on that order will be set to the same shipping address as on the original order that the customer placed for the subscription.

Only admins can change the shipping address of the original subscription order. To do this, first find the subscription ID of that customer. In Magento (you can use your Stripe dashboard if you like), one possible location is the comments section of a recent recurring order:

Magento Stripe Subscriptions Shipping Address

Once you have the subscription ID, find the recurring profile from Sales > Recurring Profiles. Click on the profile and select the Related Orders tab on the sidebar:

Magento Stripe Subscriptions Shipping Address

This is the original order that was placed for this subscription. Click on it and edit the shipping address as needed:

Magento Stripe Subscriptions Shipping Address

Once you have changed the shipping address of the original order, all subsequent recurring orders will be created using this address.

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/locale/en_US/Cryozonic_StripeSubscriptions.csv

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

app/locale/en_IT/Cryozonic_ StripeSubscriptions.csv

Make sure to replace en_IT 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.

Troubleshooting

Enable Error Logging

The module will log any problems during checkout in Magento's System Log file. To take advantage of this feature, you will need to enable logging from System > Configuration > Developer > Log Settings.

You can easily filter the log file to only the relevant messages using the following command (if you have shell access):

$ grep Stripe var/log/system.log

If you do not have shell access, just download the file, open it with your favourite text editor and search for «Stripe».

Enabling error logging will also write under var/log/exception.log and under var/report/. Make sure that these directories are writable by your Magento installation.

If you are testing on a development website, you can also set Magento to display exceptions at the front-end by running the following command:

$ cp errors/local.xml.sample errors/local.xml

Front-End Crash (Website does not load)

If for any reason the installation has caused the entire Magento site to crash, causing your website to not load, the first thing you need to do is to check for a maintenance.flag file in your Magento root directory. This file gets created if a critical error has occurred with Magento. Just delete this file to restore website functionality.

Continue to Next Step button does not work (stuck spinner)

This is an indication of a server side error (with code 500). To check if it is a 500 error, you can use your browser's debugging console – for example in Chrome you can right-click and select Inspect.

If it is a 500 error, then under the Network tab of the console you will see a red network request as shown in the screenshot below:

Magento Stripe Subscriptions Troubleshooting

To find out what is causing the error, click on the line. You will see the error under the Response tab of the network request as shown below:

Magento Stripe Subscriptions Troubleshooting

The error will give some clues as to where the crash is coming from. Usually it is some incompatibility with another module that tries to interfere with the checkout process, like triggering of custom emails, reward point modules etc. You can try to disable any such suspected modules by moving their xml file from app/etc/modules/ into a different directory. Do not try to disable conflicting modules from the admin area – it doesn't always work.

If you can't find the error from the browser console, you can additionally check in your web server's error log files and in Magento's error log files under var/log/.

Once you find the cause of the error, if you think that it is a crash with the Stripe module, send us the full error report to info@cryozonic.com to receive further help. Otherwise if the error is thrown by another 3rd party module, you may be able to solve it faster by contacting the support team of that module.

Continue to Next Step button redirects to the shopping cart

This is the same as above – a 500 server side error, please see the above section for instructions. The main difference for finding the error cause will be that you will need to check the «Preserve log» checkbox in the debugging console so that the error message does not disappear after the redirect.

Broken Admin Area

If your Magento admin has broken (i.e. receiving a white screen of death) immediately after the installation, you may have forgotten to disable compilation mode before the installation. If you've got shell access, try running the following command to disable compilation:

$ php shell/compiler.php disable

If that doesn't work, try commenting out the two define function calls in:

includes/config.php

The above should fix the issue if it is compilation-related.

If the CSS/JS of your Magento admin have broken, it may be a merged CSS/caching issue. Have a look here on how to disable merged CSS manually. You can then flush all the caches.

Finally, this can happen because of insufficient write permissions on the var/cache directories. If that's the issue, make sure that your Magento directory is owned by the same user that is running the web server before installing the module or configure your webserver to run as the same user that deploys these files to your website.

$ chown –R <www-username> /magento_directory

Failed/Partial/Corrupted Installations

If you have received errors in the black installation console, or you get crashes during the checkout page only, you may have a partial/corrupted installation because of incorrect filesystem write permissions. For corrupted installations you will need to manually uninstall the module by deleting the following files:

Stripe Payments module

app/code/community/Cryozonic/Stripe/
app/design/adminhtml/default/default/template/cryozonic/
app/design/frontend/base/default/template/cryozonic/
app/design/frontend/base/default/layout/cryozonic_stripe.xml
app/design/adminhtml/default/default/layout/cryozonic_stripe.xml
app/design/frontend/base/default/layout/customer/savedcards.xml
app/etc/modules/Cryozonic_Stripe.xml
app/locale/en_US/Cryozonic_Stripe.csv
skin/adminhtml/base/default/cryozonic_stripe/
skin/frontend/base/default/cryozonic_stripe/
lib/Cryozonic

Stripe Subscriptions module

app/code/community/Cryozonic/StripeSubscriptions
app/design/frontend/base/default/template/cryozonic_stripesubscriptions
app/design/frontend/base/default/layout/cryozonic_stripesubscriptions.xml
app/etc/modules/Cryozonic_StripeSubscriptions.xml
app/locale/en_US/Cryozonic_StripeSubscriptions.csv

You will also need to clean the database:

  1. Drop the mysql table cryozonic_stripesubscriptions_customers
  2. Open the mysql table core_resource, find and remove the entry for cryozonic_stripe_setup and cryozonic_stripesubscriptions_setup

A corrupted installation may be caused by incorrect Magento directory permissions. Most of these problems can simply be fixed by changing the ownership of the Magento directories to the user running the webserver with:

$ chown –R <www-username> /magento_directory

Alternatively you can configure your webserver to run as the same user that deploys these files to your website.

If you do not have shell access to run the above command, the only other solution would be to perform a manual installation and upload the files to your Magento directory over FTP.

Nominal item can be purchased standalone only.

A customization that you made or some other 3rd party module is overriding a class that Stripe Subscriptions is also overriding. The code that makes Magento allow multiple subscriptions to be added to the same cart is the method addItem() in app/code/community/Cryozonic/StripeSubscriptions/Model/Quote.php. In this case, the Mage_Sales_Model_Quote model is probably overwritten somewhere else in the codebase. You can get a hint of where this model is overwritten with the following command in your Magento root directory:

$ grep -iR '<quote>' *

No Shipping Methods Available

Magento ships with 8 core shipping methods. These shipping methods can be used with regular products, however when it comes to subscriptions, only the «fixed» rate shipping methods can be used for recurring profiles, which are the «Flat Rate», «Table Rates» and «Free Shipping» methods. This is an inherent limitation with the implementation of the core Magento shipping methods.

If you need more flexibility than the offered core shipping modules, you can check in the marketplace for more flexible shipping modules that support recurring profiles. For example, WebShopMatrix's free shipping module does not support recurring profiles (see here for details), however their premium module comes with support for them.

If you cannot find an appropriate shipping module for your shipping provider of choice, a last resort would be to use a fixed rate module and charge a shipping rate geographically that will have a margin of safety above the actual shipping cost that your shipping vendor will charge you.

Missing Grand Total for subscriptions

Magento does not normally display a grand total for products that have recurring profiles configured. The reason is because Magento was designed to only allow a single subscription product in the cart at a time. The fact that you are able to add multiple subscriptions to the cart is because Stripe Subscriptions overrides Magento to allow this feature.

Furthermore, because of the above Magento design, separate orders will be created for each subscription product in the cart, and separate charges will be displayed in the customer's bank account for each purchased subscription. This would allow customers to cancel/pause/resume subscriptions individually from their customer account section using the default Magento features for recurring profiles. Changing any of this behaviour would require large foundational changes in a variety of core Magento modules.

For this reason, Stripe Subscriptions does not try to do too much other than enabling the customer to add mixed products in the cart. If you still need to add a grand total, your theme developer can adjust the following templates in the module for the purpose of aggregating the totals:

app/design/frontend/base/default/template/cryozonic_stripesubscriptions/checkout/total/nominal.phtml
app/design/frontend/base/default/template/cryozonic_stripesubscriptions/tax/checkout/grandtotal.phtml
app/design/frontend/base/default/template/cryozonic_stripesubscriptions/tax/checkout/subtotal.phtml

The corresponding blocks for these templates can also be found at:

app/code/community/Cryozonic/StripeSubscriptions/Block/Checkout/

Missing Pause/Cancel Buttons

If customers cannot see the Pause or Cancel buttons on their subscriptions page, this may be because some themes intentionally hide the buttons, either with CSS rules, template editing or xml layout updates.

To confirm if your theme is hiding the buttons, you can try reverting back to the default Magento theme. The customer should then be able to see the two buttons as shown in this screenshot.

Thanks

Thank you for choosing our Stripe modules. If you like the modules, we would much appreciate a review on magento connect.