Adding Products to your Cart

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+).

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

NOTE: Subscriptions do not currently support tax or shipping (but we're working on it). Subscription products require v0.2.2+.

• 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.

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 and c for product code.

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}">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+. Discounts can be applied per product, or per category (set up in the admin). There are 3 different types of quantity discounts.

1. All-Units Quantity Discounts discount all the units. So if you get 10% off when you order 100+ units, all 100 units get the 10% off.
2. Incremental Quantity Discounts discount only the units above the tiers you set. 10% off when you order 100+ units only applies the 10% discount to the units from the 100th unit and up. So if you order 150 units, 100 are at regular price and 50 are at 10% off.
3. Buy One, Get One (BOGO), which are in many ways a repeatable incremental discount, have a single tier that can repeat. Examples include “buy one, get one free”, “buy 3 get the 4th 50% off”, etc. They repeat, so “buy one, get one free” ⇒ “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 looks like this:

&discount_quantity_amount=Quantity Discount{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{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 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}

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.

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 create your own email receipt script using the XML datafeed.

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.

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>