−Table of Contents

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.

Product Attributes

Standard Attributes

Downloadable Products

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.

Custom Attributes

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

Subscription Attributes

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.

Subscriptions and recurring billing are more involved than non-recurring billing. Please ensure you have thoroughly reviewed the subscription notes to ensure your gateway will work with FoxyCart's subscription processing system.

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.

Changing Price, Weight, or Product Codes with Attributes

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:

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

Discounts

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

Discount Types (Price, Percentage)

There are currently four types of discounts:

Discount SYNTAX and EXAMPLES

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}

All-Units Discounts

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.

Incremental Discounts

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

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

BOGO / Buy One, Get One / Repeatable Incremental Discounts

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:

Excluding Attributes

Session Attributes / "Hidden" Attributes

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.

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

Cart Options

Cart Display & Output Options

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

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

Viewing the cart

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

Direct to Checkout / Checkout Now

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>

Emptying the cart before adding a product

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" />

Allow your customer to update their contact or payment info

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.

Adding Multiple Distinct Products At Once

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