Subscriptions and Recurring Billing

• Subscription parameters
• Subscription XML Datafeeds

By default, most gateways require the CSC (card security code) 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.

Worth noting is that for all regular transactions 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.

• PayPal Website Payments Pro isn't recommended for a few reasons.
• PayPal Standard / Express Checkout subscriptions aren't supported as of FoxyCart v060.

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 immediately be set to “inactive”, and will not be processed. This is intentional, since the last thing you want to do is a bunch of testing with subs, then to go live and have dozens or hundreds of test subscriptions running and erroring and causing problems.

If you do want to test, just run the transaction, go into the FC admin and activate the subs (there's a checkbox). Then they'll run as expected.

FoxyCart v050+ subscriptions have a sub_token that allows greater flexibility with subscriptions. This token is available in the subscription XML datafeed, and also in your FoxyCart admin.

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. 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. You can manually override the sub_startdate if desired, however.

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

Updating payment information is as simple as sending the customer to the checkout via a cart==updateinfo method (documentation here). This will send the customer through the checkout and they can enter new credit card information.

Here's a step-by-step:

• Send your client an email asking them to update their payment method
• Include a link in your email similar to https://EXAMPLE.FOXYCART.TLD/cart?cart=updateinfo (replacing “EXAMPLE.FOXYCART.TLD” with your store URL)
• Upon completion the customer will receive an email “receipt” for a $0 transaction. If you have your store admin email address set to receive BCC emails you'll see a copy as well.

That said, it may be a better idea to use the method described below, as it will ensure you receive payment for any past due amounts as well.

When the sub_token paremeter is passed in the existing subscription is loaded. If the subscription has a past due amount (set automatically, but also configurable in the FoxyCart admin) this amount will be included on an attempted checkout as well.

The best way to collect past due payments and update is to append the &cart=checkout to your sub_token URL. This will send the customer directly to your checkout

If you have a customer that would like to move a subscription payment to a new customer record entirely you can follow the method above. This will allow them to enter a new email address, which will in turn create a new customer record upon successful payment.

FoxyCart v050+ allows customers to update or cancel their own subscriptions. This works by having the customer load up the subscription to their cart using the sub_token (and optionally the sub_cancel) parameter. The sub_token is available both on your subscription page in your FoxyCart admin and in your XML Datafeed.

Worth noting is that as of v060 and prior, the sub_cancel action basically sets the sub_enddate to the next available cancellation date (generally either “today” or “tomorrow” depending on the time of day). If you want more control over the cancel dates you can use sub_enddate rather than a sub_cancel. More details about subscription parameters.

Note: 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. A future update to the subscription API will improve this functionality.

1. Go to your “Subscriptions” page in your FoxyCart admin and locate the subscription you'd like to edit. Click the “Edit” link for that subscription.
2. You can easily modify all the fields listed (frequency, next date, end date, and past-due amount”, as well as the “active” checkbox. Note that unchecking the “active” checkbox will not be noted on the subscription XML, so to cancel we recommend setting the “next date” to the next allowed date.
3. If you'd like to edit the subscription itself (the products that make up the subscription), you'll need to copy the ''sub_token'' URL (or just click it to open) in a new tab. This will open a cart (replacing any current cart contents) that will effectively be a “template” of the subscription.
4. To modify the subscription, add any further subscription elements to the cart. So, navigate to the “add to cart” pages that contain the subscription you'd like to add to the cart to add to (or replace) the existing subscription. You'll notice that the cart has a warning stating “You are currently modifying a subscription.” So long as that warning is there through the cart and checkout, you are modifying the existing subscription's “template”.
5. Once you have added additional subscriptions (which automatically have their start date set to the next date for the existing subscription) you can remove the old subscription product from the cart if desired.
6. Continue to add/remove subscription products from the cart until the cart is what you'd like the new subscription to be.
7. Use unified order entry to checkout on behalf of your customer (if you're an admin), or direct the customer to complete checkout.
8. The old subscription values have been replaced by the new.

For help, please post in our forum.

1. Login to your FoxyCart Account
2. Select the appropriate store you wish to modify
3. Under the Products Menu, select Subscriptions
4. Find the Subscription you wish to modify
5. Click the edit link next to the Subscription you wish to modify, make your change then hit the update button. You're done!

Fields you can alter:

• Active (checkbox). If a subscription is not “active” it will not run.
• Amount
• Frequency
• Next transaction date