====== Creating subscription products ======

<WRAP center round info 70%>
**Just getting started with Foxy?**

This article assumes you have an understanding of how product add to carts work with Foxy. If you're not familiar with that yet, then please [[v:2.0:getting_started:products|take a look at the introductory article here]].
</WRAP>

Along with normal products, Foxy also supports the ability for customers to purchase recurring or subscription products, that charge the customer on an ongoing basis at a frequency that you set. This can open up a whole range of additional possibilities such as allowing customers to purchase ongoing access to private sections of your website, regular box subscriptions or recurring donations.

Subscriptions in Foxy are essentially the same as our normal products, but with just a few more product parameters that allow you to configure how the subscription is structured.

===== Subscription Product Parameters =====

The following parameters can be used to make your product a subscription:

  ; ''sub_frequency''
  : **Description:** The frequency of the subscription (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 Foxy.
  : **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, Foxy will set the subscription 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:** <wrap round important>A ''sub_frequency'' is required for a product to be treated as a subscription by FoxyCart.</wrap>

  ; ''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 immediately 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 the 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 set the start date to today's date.
    * Subscription start cates are not currently tied to a store's timezone settings. Test your start and end dates thoroughly or [[https://foxy.io/contact|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 January 31, it will run on the February 28, March 31, April 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 also 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, 2025 that is supposed to run for six months and then stop, set ''sub_endate'' to 20250602 (June 2nd, 2025) so that the transaction on June 1st is not cancelled by the end date.


===== Creating a subscription product =====

Continuing our example bakery, let's offer customers an option to subscribe to a regular delivery of cookies. As a simple subscription, this is what a subscription add to cart link would look like for a weekly subscription:

<code>https://example.foxycart.com/cart?name=Recurring+Cookie+Box&price=9.99&code=cookie+box&sub_frequency=1w</code>

For subscriptions, they can often benefit from configurable options, so will commonly use a form. Let's convert the recurring cookie box product to a form, and allow the customer to select how often the delivery should happen, and also what date to start on:

<code html>
<form action="https://example.foxycart.com/cart">
	<input type="hidden" name="name" value="Recurring Cookie Box">
	<input type="hidden" name="price" value="9.99">
	<input type="hidden" name="code" value="cookie+box">
	<input type="hidden" name="weight" value="0.7">
	<label for="sub_frequency">How often?</label>
	<select name="sub_frequency" id="sub_frequency">
		<option value="1w">Weekly</option>
		<option value="2w">Every 2 weeks</option>
		<option value="1m">Every Month</option>
	</select>
	<label>Beginning on?</label>
	<input type="date" name="sub_startdate">
	<button>Add To Cart</button>
</form>
</code>

<WRAP center round tip 95%>
This example form uses the default HTML date field - but you would likely want to use a javascript library of some kind to allow for some improved functionality such as only allowing dates beginning from tomorrow, and perhaps restricting the ability to select specific dates like weekends.
</WRAP>

==== A relative start date example ====

As another example of a subscription add to cart, here's a link for a "Cake of the Month Club" product, which always charges on the 5th of the month:

<code>https://example.foxycart.com/cart?name=Cake+of+the+Month+Club&price=15&code=cakeclub&sub_frequency=1m&sub_startdate=5</code>

<WRAP center round info 95%>
Depending when you interact with that link - the subscription might actually start next month if it's already past the 5th of the current month.
</WRAP>

===== Managing subscriptions =====

While not related to an add to cart, as a subscription is an ongoing agreement with a customer, it's important to also quickly talk about managing subscriptions in Foxy.

As a merchant, it's possible to manage subscriptions from within the Foxy administration, including updating subscription details and cancelling. There are also configuration options on the store for setting how failed payments should be handled, including automatically retrying or cancelling, and whether to charge for any missed payments or not.

From the customers perspective, you can utilise [[v:2.0:customer_portal|our customer portal]] to allow them to log in and view their active subscriptions and transaction history. From here, if you allow, they can also pause their subscription by changing the next date, or cancel the subscription.

===== Other Products =====

  * [[v:2.0:getting_started:products|Getting started with Foxy products]]
  * [[v:2.0:getting_started:products:bundled_products|Adding multiple products to the cart in a single add to cart]]
  * [[v:2.0:getting_started:products:option_modifiers|Modifying code, price and weight based on customer selections in a form]]
  * [[v:2.0:getting_started:products:downloadables|Creating downloadable products]]