less than a minute read • Updated 10 days ago
How subscriptions work
An introduction to how Foxy handles recurring billing, what to know before getting started, and the key limitations to be aware of.
Foxy handles recurring billing by securely storing your customer's payment information and automatically processing charges on a schedule you define. Unlike gateway-specific subscription solutions, Foxy gives you full control over billing frequency, start dates, and how failed payments are handled — without being locked into a single payment provider.
Subscriptions are accessible in three ways:
By you, through the Foxy admin or API
By your customers, through links included in their receipt emails by default
By developers, through the API and Subscription XML Datafeed
Foxy uses its own subscription processing functionality to bill for Foxy services — and has from day one. So if you're wondering how robust it is, you can take comfort in the fact that if it breaks, we lose money too.
Before you get started
There are a few important things to understand before setting up subscriptions.
Failed payments are normal. Credit cards expire, get canceled, or become overdrafted. If you have 100 customers on a monthly subscription, expect a handful of failures each month. Foxy can be configured to automatically retry failed payments and send reminder emails, but you'll need to monitor errors and follow up with customers. Often a customer simply needs a reminder to update their payment information.
Foxy does not send failed payment emails by default. Automatic retry and reminder emails must be configured in your store's advanced settings. See Failed payments & retries for details.
Your payment gateway needs to be configured for subscriptions. Most gateways require a card security code (CSC/CVV) by default, which cannot be stored or sent for recurring transactions. If your gateway is not configured correctly, all subscription renewals will fail. See Gateway requirements for subscriptions before going live.
Custom shipping snippets do not work with subscriptions. Shipping snippets run as JavaScript in the browser, but subscriptions are processed entirely on the server side. Subscriptions will always calculate shipping based on how the store category is configured.
Testing is required before going live. Subscriptions created while your store is on test payment servers renew on their normal schedule, charged against your test gateway. That means you can test renewals, receipt emails and webhooks without using a real card. To see a renewal quickly, give a test product a 1-day frequency, or change a test subscription's next charge date to tomorrow. Renewals run once a day, early in the morning Pacific time — see When do subscriptions process. For a full pre-launch checklist, see Test your store using these best practices.
Cancel test subscriptions before switching to live payments. A renewal always uses whichever gateway your store is set to on the day it runs. Once you switch to live servers, any test subscription that is still active will try to charge its saved test card on your live gateway. That charge will fail, and if you've set up retries and reminder emails, the customer on that subscription will receive them. Cancel your test subscriptions first, or use a separate store for testing.
What happens on each renewal
When a subscription renews, some details are taken from the subscription itself and some are recalculated from your store's current settings. Knowing which is which tells you whether a change you make will reach your existing subscribers automatically, or whether you need to update each subscription.
Saved on the subscription. These are set when the subscription is created and stay as they are until you change them on that subscription:
The price and quantity of each item
The products themselves, including their options
Any discount applied to an item
The billing frequency, next charge date and end date
Because these live on the subscription, changing a product in your store doesn't change what your existing subscribers pay. To change those, edit the subscription — see Change Existing Subscription Price in the Foxy Admin and Update the Products in a Customer's Subscription.
Recalculated on every renewal. These are worked out fresh each time using your current settings and your customer's current details:
Taxes
Shipping
Handling fees
The customer's billing and shipping address, taken from their customer record
The customer's saved payment method
Because these aren't stored on the subscription, changes to them apply to your existing subscriptions automatically. If you add a tax or a handling fee, or a customer updates their address or card, the next renewal picks it up without you editing anything.