To add a product to your cart, there are two methods you can use: a form or a link. Forms have many potential advantages, including the ability to use dropdowns or other input fields to set options (like size, color, etc.). To add a product using a form, you

<form action="https://YOURDOMAIN.foxycart.com/cart" class="foxycart" method="post">
	<input type="hidden" name="name" value="A great product" />
	<input type="hidden" name="price" value="5.00" />
	<input type="submit" value="Buy It Now!" />
</form>

Or in a link, like so:

<a href="https://YOURDOMAIN.foxycart.com/cart?name=A%20great%20product&price=5" class="foxycart">
	Buy this Great Product!
</a>

Note the foxycart, class which opens our own version of Cody Lindley's Thickbox. Also, %20 may look scary, but it's just a URL Encoded space. You can put a space in instead, but your links won't be valid (X)HTML. If you're using MODx, you can do this automatically.

• name: The name of the product that will be displayed in the cart.
• price: The cost of the product. DO NOT enter a currency sign.
• code: Item code, can be used however you’d like.
• quantity: Quantity of products. If left blank, it will default to 1.
  • quantity_max: Maximum quantity that should be allowed per cart, per product, per cart.
  • quantity_min: Minimum quantity that should be allowed per cart, per product, per cart.
  • NOTE: Max and min quantities do not control inventory. The values are per cart/transaction/session.
• category: Category identifier for the product. This will default to the default category if left blank.
• weight: Weight, used for shipping. If left blank, it will inherit this value from the product’s category. If no category selected, will default to the default category's weight.
• shipto: Allows you to specify specific shipto address labels for each cart add (requires multiship feature v0.3.0+).
• coupon=coupon_code. Add a coupon code directly to the cart. (v0.4.0+) See the discount syntax below and in the admin help for more information on how to configure coupons for your store.

Downloadable products are configured in the FoxyCart admin. The price, name, and code are all set there, so when adding a downloadable product you just need to pass in the code attribute and the category that you've configured as a downloadable category. More info about selling downloadable products in FoxyCart.

FoxyCart will assume that all parameters it receives are product options.

• CUSTOM ATTRIBUTES: You may add any additional attributes to any product you’d like. For example, you can add &color=green&size=XXL

Subscription products require v0.2.2+. Subscriptions with Tax and Shipping require v0.5.0+. Stores using multiship do not currently support future subscription taxes.

• sub_frequency: Frequency of subscription. This is required for (and defines a product as) a subscription. The format is DDx or Dx where D is a number and 'x' is a unit of time. Possible values include:
  • 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.
• sub_startdate: 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.) 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. Optional. Will default to today's date.
  • YYYYMMDD = Example: 20070131 = January, 31 2007.
  • 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.
• sub_token: (v050+) Unique URL per subscription for loading your subscription up into a cart and modifying it's 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. Make sure you read the additional notes about how the ''sub_token'' works.
• sub_cancel: (v050+) Set this value to “true” along with using the sub_token to let a customer cancel their subscription. This will set the end date on the subscription to tomorrow.
• sub_enddate (v050+) Useful for setting an end date on a subscription. NOTE: As of v051, the sub_enddate parameter affects all subscriptions in a cart. Accepts YYYYMMDD formatted dates. 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, 2010 that is supposed to run for six months and then stop, set sub_endate to 20100602 (June 2nd, 2010) so that the transaction on June 1st is not cancelled by the end date.

Note: with sub_cancel and sub_enddate, your system needs to take advantage of the subscription datafeed in order to update your website based on the subscription activity (such as a cancel).

Note: Subscription products require the customer to create an account at checkout.

If you have a product option that will modify the price, weight or product code then use curly brackets( { } ) after your option value with the following modifiers:

• p for price
• w for weight
• c for product code
• y for category (v070+ only)

For example, if I want an extra large size option that adds $2.50 to the cost, change the code, and a pound to the weight, it would look like this: &size=XL{p+2.50|w+1|c:01a}. Or, if you were doing a form, something like this:

<select name="size">
	<option value="S{p+1.50|w-1|c:01a|y:teeny_category}">Small</option>
	<option value="XL{p+2.50|w+1|c:01d}">X-Large</option>
	<option value="Custom{p:5|w+1|c:01s}">Custom</option>
</select>

NOTE: Prior to v0.3.2, the delimiter was a comma instead of the pipe symbol, like this: {p:5,w+1,c:01s}

As you can see above, you can subtract values with a “-”, and you can set a value using the “:”. As of v0.3.2, the code modifier can concatenate values with the +, so if you had code=123 and a modifier of Small{c+small}, the resulting code would be 123small. (Prior to v0.3.2 only the colon, :, was allowed as a code modifier.)

For v0.3.2+ only.

Customers love discounts, and we do our best so that store owners love them too.

Discounts apply either to individual products or on all of the products in a category. Discounts on individual products are set up through the product link. Discounts on all of the products in a category are set up in the FoxyCart admin area.

The amount of the discount applied to an order depends on either the quantity of the products ordered or the total price of the products ordered. A discount can either add or subtract a percentage of the original price of a product, or a fixed amount from each product ordered. The amount of the discount changes based on “tiers” set up by the store owner. Tiers allow the store owner to specify, for example, a greater discount for orders over $100 than orders from $50–100 or, in the case of quantity discounts, a greater discount on orders of more than 20 products than given on orders of 15-20 products.

There are 3 different types of quantity discounts.

1. All-Units Quantity Discounts discount the price of all of the products ordered. Also referred to as “volume discounts” or “bulk order discounts.” Examples of this type of discount:
   1. “Buy two products, take $2 off of each.”
   2. “Orders of five or more qualify for a 10% on each item ordered.”
2. Incremental Quantity Discounts discount only the units above the tiers you set. Examples of this type of discount:
   1. “Buy two products, get the next two at $5 off”
   2. “Order 100 units, take 10% off of the next 100”
3. Buy One, Get One (BOGO), or “repeatable” discounts, only have a single tier. Examples of this type of discount:
   1. “buy one, get one free”
   2. “buy 3 get the 4th at 50% off”

With Foxycart, these discounts are allowed to repeat, so a “buy one, get one free” discount also translates into “buy two, get two free”.

There are currently four types of discounts:

• discount_quantity_amount: The tiers are determined based on quantity, and the discount is a set amount taken off the price.
• discount_quantity_percentage: The tiers are determined based on quantity, and the discount is a percentage of the price.
• discount_price_amount: The tiers are determined based on the value of the products, and the discount is a set amount taken off the price.
• discount_price_percentage: The tiers are determined based on the value of the products, and the discount is a percentage of the price.

The syntax for entering discounts (or coupon codes) looks like this: DISCOUNT NAME{TIER-DISCOUNT} or DISCOUNT NAME{TIER+DISCOUNT}

Note that you must URL-encode the discount name in your product links, so your discounts will look like, for example, DISCOUNT%20NAME{TIER-DISCOUNT}.

As described above, the tiers can be based on the value or the quantity, and the discounts can be a set amount or a percentage. So if you wanted to do a discount like “All orders over $75 get $25 off of each product”, it'd look like this:

<a href="https://YOURDOMAIN.foxycart.com/cart?name=A%20great%20product&price=50&discount_price_amount=My%20Discount{75-25}" class="foxycart">
	Buy this Great Product (Purchases over $75 receive $25 off!)
</a>

The important code syntax being:

&discount_price_amount=My%20Discount{75-25}

You've named the discount “My Discount”, set the discount to the appropriate discount type, set the tier to be $75, and set the discount to be $25. Similarly, if you wanted to do a discount like “$25 off all T-Shirt orders” (with no minimum, perhaps assuming that your shirts are $50 to begin with), it'd look like this:

&discount_price_amount=Winter%20Special{26-25}

We've set the tier to $26, at which point a $25 discount is applied. This might make more sense as “$25 off when you buy 2 T-Shirts!”:

&discount_quantity_amount=Summer%20Sale{2-25}

In this case, the tiers are determined by quantity, not price (as above), so this code says “once 2 shirts are in the cart, apply a $25 discount”. You could change the discount from $25 to 25% by changing the discount type to discount_quantity_percentage.

You can also set multiple tiers, so you could say “$25 off T-Shirt orders over $100, $50 off T-Shirt orders over $200” by doing:

&discount_price_amount=Winter%20Special{100-25|200-50}

The syntax looks like this:

&discount_quantity_amount=Quantity Discount{allunits|5-1|10-2|25-5}

This would set 3 quantity-based tiers of discounts for the product. At 5 products, each product would get $1 off. At 10 products, each would receive a $2 discount. At 25 products, each would receive a $5 discount. You could also do a price-based discount:

&discount_price_percentage=Value Discount{allunits|50-5|100-10|250-20}

This would also set 3 tiers, the the tiers are based on the price of the item(s). If the item was $25/each, then at 2 items (2x$25=$50) you'd get a 5% discount. At 4 items (4x$25=$100) you'd receive a 10% discount. And at 10 items (10x$25=$250) you'd receive a 20% discount.

The allunits flag is the default behavior for quantity discounts. Prior to v070 you should not actually include allunits in your discount string, as it is implied. As of v0.7.0 it can be included explicitly if desired.

The syntax and logic is the same as above, but you must add the incremental “flag” ahead of your tiers, like this:

&discount_quantity_amount=Quantity Discount{incremental|5-1|10-2|25-5}

“Single” discounts are the default discount type for coupon codes. It is similar to the “all-units” discount but the discount specified is applied only once for the total transaction and not per unit. Let's take the following:

&discount_quantity_amount=Quantity Discount{single|5-1|10-2|25-5}

At a quantity of 5 a single $1 discount would be applied to the transaction as a whole. At a quantity of 10, a single $2 discount is applied. At quantity>=25, a single $5 discount is applied.

The single flag is the default discount type for coupon codes if no other discount type is specified, and is only available from v0.7.0 and up. (v0.6.0 and earlier default to single, but cannot be switched to allunits.)

The syntax and logic is the same as above, but you must add the repeat “flag” ahead of your tiers, like this:

&discount_quantity_percentage=Quantity Discount{repeat|2-100}

Notes about repeatable discounts:

• Repeatable discounts can only have one tier.
• discount_quantity_percentage or discount_quantity_price make the most sense for repeatable discounts.

• EXCLUDING ATTRIBUTES: Sometimes you may need values in a form or link that you don't want to pass to the cart. To do this simply prefix the attribute name with x:, like x:name=value, and the attribute will not be passed into the cart as a product option.
• v0.2.8+: Double underscores as a prefix, __, exclude the attributes as well. Helpful for Google Analytics.
• Other parameter names that are protected or excluded (in addition to the list at the top of the page) are:
  • cart
  • empty
  • output
  • sub_token
  • sub_enddate
  • callback

Useful for synching custom fields between FoxyCart and your own system, or using information from an external system to manipulate FoxyCart. For example, you could pass in a customer ID value that would sync back to your own database.

• v0.3.0+: h: used as a prefix will hide whatever custom field you send to the cart and make the values available to the cart fc_json object and the datafeed. Example: h:my_user_id=10

Session attributes are not emailed. If you need these values in an email you'll need to:

• Grab the value from the JSON on the checkout, and populate your own custom field with it so it becomes part of the checkout. This could be useful as well if you want the user to be able to update their information on checkout. (If you don't, you could make it a hidden input, so long as it is inside the checkout's form element.)
• Create your own email receipt script using the XML datafeed.

The &cart parameter controls a wide variety of behaviors. Specific behaviors are explained below, but a quick list is:

• cart=view
• cart=checkout
• cart=checkout_paypal_express (v060+, direct to PayPal Express Checkout)
• cart=updateinfo

There are other cart parameters that affect the cart in its entirity (as opposed to product parameters, which affect a specific product):

• empty=true. This will clear the contents of the cart. (Products can be added in the same request.)
• coupon=coupon_code. Add a coupon code directly to the cart. (v0.4.0+) See the discount syntax above and in the admin help for more information on how to configure coupons for your store.
• redirect=path/to/file.ext. (v0.4.0+) Immediately redirect the user to a page on cart load, such as &redirect=index.html.
  • NOTE: The value of the redirect parameter will be prefixed with your store URL domain, as specified in your store settings. So if your store domain is example.com, you can only redirect back to example.com. This is to prevent potential phising attacks. Also, (prior to 041), you'll have to remove class=“foxycart” on your forms and links using this method to avoid redirecting within the thickbox. Also, don't use cart=checkout along with the redirect feature as it will take you to the checkout instead of redirecting you.
• output=json. (v0.4.0+) Specify the output format. Possible values are html (default) and json, which will load the JSON cart object.
  • NOTE: In v0.4.0 the cart=view parameter must be passed along with output=json in order for JSON to display.
  • JSONP support is available as well. If output=json then the optional callback parameter is supported as well.

Load the cart like this:

<a href="https://YOURDOMAIN.foxycart.com/cart?cart=view" class="foxycart">
	View your cart.
</a>

It's probably a good idea to call this link the same way you call your “add to cart” links (ie. with foxybox).

If you'd like to create a “Checkout Now” link or if you'd like to add just one product and go directly to the checkout screen (this might be useful, for example, when setting up conference registrations):

<a href="https://YOURDOMAIN.foxycart.com/cart?cart=checkout" class="foxycart">
	Checkout Now
</a>
<a href="https://YOURDOMAIN.foxycart.com/cart?name=test&price=10&cart=checkout" class="foxycart">
	Add this product and checkout
</a>

When using a form, just include a hidden text input:

<form action="https://YOURDOMAIN.foxycart.com/cart" class="foxycart" method="post">
	<input type="hidden" name="name" value="A great product" />
	<input type="hidden" name="price" value="5.00" />
	<input type="hidden" name="cart" value="checkout" />
	<input type="submit" value="Checkout Now!" />
</form>

Simply add &empty=true to your link (or an input with name=empty and value=true) to your cart add and it will empty the cart before adding the product. So, for a form, you would add:

<input type="hidden" name="empty" value="true" />

Simply send your customers to your cart page with ?cart=updateinfo in the URL. This will direct them to your checkout page and allow them to update their contact information or payment method without actually buying anything. This works really well in conjunction with subscriptions.

Let's say you want to add separate products to your cart in one pass, like a Zune and a Zune case. To add multiple unique products at one time, prefix the attributes with a number from 2-99 followed by a colon, like this:

<form action="http://YOURDOMAIN.foxycart.com/cart" class="foxycart" method="post">
	<input type="hidden" name="name" value="A Brown Zune" />
	<input type="hidden" name="price" value="199.99" />
	<input type="hidden" name="2:name" value="A Zune Leather Case" />
	<input type="hidden" name="2:price" value="9.99" />
	<input type="submit" value="Buy a Zune and a leather case!" />
</form>

Or in a link, like so: (spaces added for legibility)

<a href="https://YOURDOMAIN.foxycart.com/cart?
	name=A%20Brown%20Zune
	&amp;price=199.99
	&amp;2:name=A%20Zune%20Leather%20Case
	&amp;2:price=9.99"
	class="foxycart">Buy a Zune and a leather case!</a>

(Note: the number preceeding the attribute must be 3 or less digits, 4 digits or more will result in an error upon adding items to cart.)