• Subscription Product Options
• The API
• Subscription XML Datafeed
• PHP Subscription XML Datafeed Processor (to create automated billing reminder emails, etc.)

FoxyCart allows merchants to process subscription and recurring-billing types products in a secure and flexible way, without relying on gateway-specific solutions with are often costly and less flexible for the merchant and the customer. To do this, FoxyCart securely stores the customer's payment information, and provides access to subscriptions to the merchant through the FoxyCart admin, to the developer through the API, and to the customer through a variety of link possibilities (included in the email receipts by default).

Recurring revenue streams can be a game-changing business decision, but it is important to understand a few things.

1. Recurring billing will fail with some regularity. Credit cards methods expire, become overdrafted, are canceled due to fraud or identity theft, and more. If you have 100 customers on a monthly billing arrangement, it is completely natural for at least a handful to error in any given month. If you want to get paid, you will need to monitor errors and followup with customers. Often times customers simply need a reminder to update their payment information.
2. FoxyCart does not (at this version) send customers emails if their payment fails or if their payment method is soon to expire. FoxyCart attempts to minimize any assumptions about a merchant's business processes, so we encourage you to create your own billing reminder emails and notifications using the Subscription XML Datafeed and something like PHP Subscription XML Datafeed Processor. If you have questions please post in our forum.
3. Some gateways may have additional steps to allow FoxyCart to process subscriptions. Please see the notes below for explanation, and always test, test, test before going live.

Custom shipping snippets do not work for subscriptions. The reason for this is because the snippets are done as Javascript modifications and run in the browser, while subscriptions run completely on the server side and never touch the browser. Subscriptions will always calculate on the server side based on how the category is configured.

By default, most gateways require the CSC (card security code, also called the CVV2, CVC2, or CCID) to be sent with the payment details. Because storing the CSC is prohibited per PCI DSS, FoxyCart sends the subscription transactions without the CSC. If your gateway is set to require the CSC, the transaction will fail, effectively rendering FoxyCart's subscription functionality useless.

Depending on your gateway provider and account settings you may be able to configure this yourself, or you may need to ask your gateway's support to change your account for you. Please review the notes for your gateway. Even if there are no notes specific to subscription handling on our wiki, you should still dig into the CSC settings on your gateway. And test to ensure recurring payments process correctly.

Worth noting is that for all regular transactions through FoxyCart the CSC is required on checkout. The only way the CSC will not be sent to your gateway by FoxyCart is for a subscription transaction.

Testing is a REQUIRED STEP when using subscriptions with FoxyCart. Check the testing page for more details.

Important to note is that while your FoxyCart store is in test mode, any subscriptions you process will be set to “active”, and will be processed once you switch over to the Live Servers.

Before you switch over to the Live Servers, make sure that you set all the subs you have created while on the Test Servers to inactive. You can do that by using the API or by changing them individually. To change them individually, go to the Manage Subscriptions section in the FoxyCart admin, click on the Edit link of the desired subscription, deactivate the sub by unchecking the Active? checkbox and then update the subscription.

It's recommended to create a separate store for testing and one for production so that you wouldn't need to deactivate all the test subs when you switch over to a Live Store.

As mentioned above, FoxyCart does not send automatic emails to customers when their payments fail, when their subscriptions cancel, or when their payment method is soon to expire. Nor does FoxyCart (currently) provide a “customer portal” where they can view active subscriptions, update billing info, or cancel subscriptions. Instead, FoxyCart provides the tools to build similar functionality as desired.

What FoxyCart does provide, however, is a variety of methods for both the merchant and the customer to update subscriptions.

The easiest way for most stores to provide customers with the means to update or cancel their subscriptions is to provide links in each and every receipt email sent to the customer. At left is an example of what we ourselves use, which is provided by default in FoxyCart's default email templates. Notice that links are provided to update the customer's billing information, to transfer the subscription to a new billing contact, and to cancel the subscription. Because these links are included in each and every receipt sent for a given subscription, it is an easy and effective way for customers to manage their own subscriptions. Also, because of the flexibility FoxyCart provides, these links can be customized as desired, removed, or extended to provide additional functionality.

If you need to modify a subscription on behalf of a customer you can accomplish this in one of three ways:

1. By using Unified Order Entry (aka “the superpassword”) to act as a customer without knowing their password.
2. Through the FoxyCart admin, by editing the subscription. (For advanced edits you can edit the raw XML.)
3. Through the API.

The Unified Order Entry method allows you to take advantage of the sub_token methods outlined below, as if you were the customer. See Unified Order Entry for details, but the basic idea is to use the sub_token to modify the subscription as necessary, then use the UOE superpassword to process the subscription on behalf of the customer.

Every subscription in a FoxyCart store has a unique sub_token, which is used both to identify the subscription (independent of customer or transaction) and to load the subscription into a customer's cart (to modify or cancel). This token is available in the Subscription XML Datafeed, from the API, and also in your FoxyCart admin (right-click and copy the URL from the “Sub Token URL” link).

When the sub_token parameter is passed to the cart, it will blow away any previous cart data and load in a “template” of what the subscription is. There are a few common use cases for this:

The sub_token can be combined with a cart=checkout directive to send the customer straight to the checkout screen (bypassing the cart), and indeed this is how the default receipt email includes the sub_tokens. When the customer lands on checkout the email address will be pre-filled with the current billing email address. At that point the customer can enter their password and complete the payment or information update as normal, or the customer can enter a new email address and take over the subscription from the previous billing contact.

It's worth noting that customers may update their billing information without the sub_token by using the cart parameter updateinfo, but for the purposes of this discussion it's likely more useful to include the sub_token. That said, if you need to allow customers to update their payment information and you don't have the sub_token available, you can use cart=updateinfo. More info is available at the cheat sheet and the documentation here.

If a customer desires to change his or her subscription, you could pair the sub_token with a redirect parameter to redirect the customer to a page on your website with links or forms for new subscriptions, or to view their cart. The customer could then add or remove items from their subscription, change quantities, or etc. Once the customer is satisfied with their new subscription they can proceed through checkout to update their subscription. Visual indication is provided to the customer on the cart and checkout page if a sub_token is active, as shown in the image at right.

Note that any new subscriptions added to the cart will automatically have the sub_startdate set to the next scheduled date for the subscription to run on, which will prevent a user from modifying a subscription that ran yesterday (for example) and being charged again for today. For example, if you have a subscription for “Chocolate of the Month” set to run on the 15th of each month, and you load the sub_token on the 25th and add a “Wine of the Month” subscription product to your cart, the sub_startdate will be set to the 15th of the next month (unless manually overridden).

Once a user completes the checkout from the sub_token that new transaction will replace the previous subscription.

Similar to the modification approach above, a subscription can be loaded to be canceled if the sub_token is passed in with a sub_cancel=true. This will change the notification to something like “You are about to set this subscription to end on 2010-10-01”, and upon checkout the subscription will be set to end. It is generally a good idea to include the cart=checkout parameter to ensure the cancellation goes straight to checkout.

When a subscription is set to cancel, it effectively sets the sub_enddate to tomorrow, at which point the subscription will not be processed (even if the sub_enddate falls on a normal billing date), and the cancellation will be included in the Subscription XML Datafeed.

FoxyCart's current implementation requires that customers attempting to cancel subscriptions pay any past due amount before they can cancel their account. If a customer needs to cancel a subscription with a past due balance you will have to do this for them through the subscription page in the FoxyCart admin.