Subscription Parameters

sub_frequency

Description: The frequency of billing (every month, every 3 months, every year, etc.).
Default: None. If this value is empty, the product will not be considered to be a subscription by FoxyCart.
Accepts: An integer (maximum of 3 digits) followed by a single character denoting the unit of time. For example,

• 60d = every 60 days.

• 2w = every two weeks. For date calculations, 1w = 7d.

• 1m = every month. When you use the m unit, FoxyCart will assign billing to the current (or assigned) day of the month, to be repeated every x months. The date will be moved up when necessary; if set to the 31st, it will process on the 30th of months with 30 days (or 28th/29th of February).

• 1y = every year.

• .5m = twice a month. IMPORTANT: The .5 value only works with m (months). This value will setup bi-monthly subscriptions, once on the start date, and again 15 days later. Example: if you set it to start on the 3rd, it will run on the 3rd and the 18th of each month.

  Notes: A sub_frequency is required for a product to be treated as a subscription by FoxyCart.

sub_startdate

Description: Subscription start date. Useful if you'd like to offer a free trial period, or to force subscriptions to process on specific dates (the 1st, 15th, 18th, etc.).
Default: If this value is left empty, the subscription will start on the date of the transaction.
Accepts: You can pass through a full date in the YYYYMMDD format or just pass in the day of this month in the DD or D format. If you pass through a day that has already past, it will start on that day next month. For a relative date from today, you can also specify an integer followed by a single character denoting the unit of time.

• YYYYMMDD = Example: 20150131 = January, 31 2015.

• DD = Example: 10 = will run on the 10th of this month or the 10th of next month if today's date is after the 10th.

• D = Same as DD.

• 60d = 60 days from today.

• 2w = 2 weeks from today. For date calculations, 1w = 7d.

• 1m = 1 month from today.

• 1y = 1 year from today.

  Notes:

• This is an optional field. Not indicating a “sub_startdate” would automatically assign it its default value.

• Subscription start and end dates are not currently tied to a store's timezone settings. Test your start and end dates thoroughly or contact us if you have questions about them.

• The day of the sub_startdate will generally be used for all subsequent billing attempts when used with a monthly frequency, but in cases where the date doesn't exist in a month, it will be moved ahead for that month. So if you have a subscription with a start date on Jan-31, it will run on the Feb-28, Mar-31, Apr-30, and etc.

sub_enddate

Description: The date a subscription should end.
Accepts: YYYYMMDD formatted date value in the future. For a relative date from today, you can also specify an integer followed by a single character denoting the unit of time.

• YYYYMMDD = Example: 20150131 = January, 31 2015.

• 60d = 60 days from today.

• 2w = 2 weeks from today. For date calculations, 1w = 7d.

• 1m = 1 month from today.

• 1y = 1 year from today.

  Notes:

• This is an optional field. Not indicating a “sub_enddate” would make the subscription run indefinitely.

• If a subscription is scheduled to run on the 4th, and the sub_enddate is the 4th, the subscription will end before it is billed to the customer. So, this parameter should be set to a date after the date you want the last transaction in the subscription to run. For example, if you have a monthly subscription starting on January 1st, 2015 that is supposed to run for six months and then stop, set sub_endate to 20150602 (June 2nd, 2015) so that the transaction on June 1st is not cancelled by the end date.

sub_token

Description: Unique URL per subscription for loading your subscription up into a cart and modifying its contents. Very useful when used in conjunction with the redirect feature as you can load up a customer's subscription and then redirect them back to your product page so they can add something to it.
Accepts: A valid sub_token (retrieved from the API, XML datafeeds, or admin).
Notes: When a sub_token is loaded by the customer, the customer's cart is emptied and replaced by the content of the subscription represented by the sub_token.

sub_cancel

Description: A flag indicating the subscription in question (as retrieved from the sub_token) should be cancelled. By “canceling”, the subscription gets a sub_enddate set, on which day it will be ended and made inactive.
Accepts: true to set the end date to tomorrow, or next_transaction_date to set the end date to the subscriptions next transaction date.
Notes:

• Requires a sub_token to function. Otherwise there will not be any subscription to cancel.

• Foxy native email receipts will include links for the customer to be able to update or cancel their subscription. The cancel link will by default be set to sub_cancel=true, so the subscription will end the following day. If you want to instead default these links to cancel on the next transaction date, you can edit the language strings for your store. On the “language” page of the Foxy administration, expand the “email” section and search for “sub_cancel=true”. There will be two instances of it - simply update true to next_transaction_date to change the links.

sub_restart

Description: A flag that makes the subscription products payable “now”, when used with a sub_token URL. This can (and generally should) be used instead of relying on past-due amounts.
Accepts:

• true: Collect payment “right now”.

• auto: Collect payment “right now” if and only if the subscription's past-due amount is greater than 0. Adding sub_restart=auto will eventually be the default Foxy behavior for updating subscriptions.

  Notes:

• This must be passed in with a sub_token or it will have no effect.

• Normally if you load up a sub_token URL, it will allow modifying the subscription, but will not change the subscription's next date, nor will it charge the customer immediately for the products in the cart. (A past-due amount will still be payable “now”, but the rest of the products will simply bill according to the subscription's next transaction date.) This flag makes the subscription charge “now”.

• This flag is almost always going to be preferable to customers paying the single lump sum past-due amount, as it ensure taxes, shipping, and product details are maintained.

• If the “reset the next transaction date on payment (past due or restart)” option on the “advanced” setting page of the Foxy administration is checked, then the next date will be updated to be one frequency ahead of todays date. If unchecked, the next date will remain as it currently is.

sub_modify

Description: Allows the “add to cart” link or form to completely replace the existing subscription loaded (in the same or a previous cart request) via the sub_token. (The default behavior is to add new products to the existing subscription, and set the frequency and dates to match.)
Accepts: replace
Notes:

• This is an optional parameter. If omitted, it will default to an “append” behavior.

• Upgrading/Downgrading: This can be useful in upgrading or downgrading subscriptions, or otherwise modifying subs. For instance, if you had a monthly membership service, you could create an upgrade link that replaces the currently loaded subscription (loaded via the sub_token) with the upgraded subscription.

• Changing “Auto-Ship” Subscriptions: Similarly, you could use this functionality to replace an auto-ship order that may have multiple different products. Let's say the customer has a subscription for Product A and B, and wants to change it to Product B and 2 Product Cs, you could build an order form that includes the sub_modify=replace param, and it would replace the customer's currently loaded subscription.

• Removing End Dates: To clear an end-date from a subscription you're replacing, pass sub_enddate=00000000.

• Prorating? At present, this does not prorate a subscription. So if you're halfway through a subscription period and replace the subscription, any change in the price between the old and new subscription total will not be prorated. We may add an additional possibilities for this parameter in the future.