Important Notes:

• All product parameters will be trimmed of excess leading and trailing whitespace when added to the cart. This can cause problems with price validation if you're not careful.

name

Description: The name of the product that will be displayed in the cart.

Accepts: Any characters.

Example: &name=My Example Product

Notes: Required.

price

Description: The cost of the product.

Accepts: Number (integer or decimal).

Example: &price=9.99

Notes: Required.

image

Description: An image for the product, displayed in the cart.

Accepts: A full URI to an image, starting with http: or https:, or a relative path to the image from the store's domain (as configured in the store settings).

Example: &image=http://example.com/path/to/image.jpg, &image=local/path/to/image.png

Notes: Images will not be resized, but they will automatically be securely cached, so you don't need to worry about security warnings.

url

Description: A URL for the product, displayed in the cart.

Accepts: A full URL to the product page, starting with http: or https:, or a relative path to the produt from the store's domain (as configured in the store settings).

Example: &url=http://example.com/path/to/product, &url=local/path/to/product

Notes: The URL will only be applied if the image parameter is also present, and will be wrapped around the image in the cart.

code

Description: Item code. Can be used however you’d like (internal use, product SKU, etc.).

Accepts: Any characters. Limited to 50 characters in length.

Example: &code=ISBN 978-0-12-345678-9

Notes: Required if using Link and Form Validation. Not required otherwise.

quantity

Description: Quantity of products. If left blank, it will default to 1.

Default: 1

Accepts: Integer. Decimals are not supported.

Example: &quantity=3

Notes: In forms it often makes sense to make the quantity input be an input[type=text] or select element to allow the customer to enter or choose their desired quantity.

quantity_max

Description: Maximum quantity that should be allowed per product, per cart.

Accepts: Integer.

Notes: This attribute, like all others, relies on the products in the cart being identical. If another product is entered with any variation, it is considered a new product. ie. quantity_max cannot apply to groupings of multiple products. Also, this value does not control inventory. The values are per cart/transaction/session.

quantity_min

Description: Minimum quantity that should be allowed per product, per cart.

Accepts: Integer.

Notes: This attribute, like all others, relies on the products in the cart being identical. If another product is entered with any variation, it is considered a new product. ie. quantity_min cannot apply to groupings of multiple products. Also, this value does not control inventory. The values are per cart/transaction/session.

category

Description: Category identifier for the product.

Default: This will default to the default category if left blank.

Accepts: Any valid category code, as configured in the store's admin. Will error on an invalid code.

weight

Description: Product's per-product weight, used for shipping rate requests.

Default: If left blank, it will inherit this value from the product’s category. If no category selected, will default to the default category's specified weight.

Notes: Supports up to a maximum of three decimal places.

length, width, height

Description: Reserved for future use. If you use them, the data will be stored in the cart JSON, but it will not display on the page.

shipto

Description: Allows you to specify specific ship-to address labels for each cart add.

Default: “me” (meaning, it defaults to the billing contact, and not a separate recipient).

Accepts: Any string. Products will be grouped by shipto value on checkout and in the cart display (if multi-ship is enabled).

Notes: Requires multiship to be enabled for the store.

id

Description: A unique ID per product in the cart, used to make “update” requests to existing products in the cart (as in a JSONP request).

Accepts: Any valid id for a product already in the cart.

Notes: This value is set by FoxyCart, and may be different in different situations. You cannot rely on any product in the cart having the same id from one session to another.

1:, 2:, 3:, 4:, etc…

Description: Prefixing any product option with an integer will group that option with other similarly numbered options, allowing you to add multiple distinct products to the cart in one request.

Default: If no grouping prefix is added, the option will be assumed to be a 1:.

Accepts: Integers from 1-999.

Notes: All product options must be prefixed in order for grouping to happen, and all required options are still required per product.

Example:

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

CUSTOM Product Options

Description: You may add any additional attributes to any product you’d like. For example, you can add &color=green&size=XXL. If an attribute is passed in with a name not otherwise reserved, it will be added as a product option.

Please see Coupons and Discounts for a complete discussion of how discounts are applied. The following is for reference only.

discount_quantity_amount

Accepts: A valid discount string.

Notes: Discounts by an amount, based on the quantity of to-be-discounted products. Abbreviated $/qty.

discount_quantity_percentage

Accepts: A valid discount string.

Notes: Discounts by a percentage, based on the quantity of to-be-discounted products. Abbreviated %/qty. Note that the value is based on the average of all applicable products, so applying this discount to differently priced items will result in an averaged discount.

discount_price_amount

Accepts: A valid discount string.

Notes: Discounts by an amount, based on the price of to-be-discounted products. Abbreviated $/$.

discount_price_percentage

Accepts: A valid discount string.

Notes: Discounts by a percentage, based on the price of to-be-discounted products. Abbreviated %/$. Note that the value is based on the average of all applicable products, so applying this discount to differently priced items will result in an averaged discount.

allunits

Also Called: All-Units Quantity Discounts

Description: Discounts the price of all of the products affected by the discount. Also referred to as “volume discounts” or “bulk order discounts.”

Notes: allunits is the default discount type for quantity discounts applied to products. If a discount type isn't specified, allunits is applied.

Examples:

• Scenario: Buy two products, take $2 off of both.
  • Method: discount_quantity_amount
  • Logic: allunits|2-2
    
    
• Scenario: Orders of five or more get a 10% on every item ordered. Orders of 10 or more get a 20% discount on every item ordered.
  • Method: discount_quantity_percentage
  • Logic: allunits|5-10|10-20

incremental

Also Called: Incremental Quantity Discounts

Description: Discounts only the units above the tiers you set.

Notes: Most useful for individual products or many products with the same price. Not useful for $/$ discount methods.

Examples:

• Scenario: Buy two products, get additional products at $5 off. (The first two are not discounted.)
  • Method: discount_quantity_amount
  • Logic: incremental|3-5
    
    
• Scenario: With a quantity of 1-10, all products are at 100%. With a quantity of 150, 10 products would be at 100%, 40 would be at 90%, 50 would be at 85%, and 50 would be at 80%.
  • Method: discount_quantity_percentage
  • Logic: incremental|11-10|51-15|101-20

repeat

Also Called: Buy One, Get One (BOGO), or “Repeatable Incremental Quantity Discounts”

Description: Repeatable discounts are somewhat similar to incremental discounts, but only have a single tier that repeats. Using this method you can achieve “buy one get one free” types of discounts that repeat (buy 1 get 1, or buy 3 get 3). You can also do something like “buy 3 get the 4th at $5 off”, so buying 5 or 6 would only get a single $5 discount, but buying 8 would get a $10 discount.

Notes: Not useful for $/$ discount methods. Only accepts one tier.

Examples:

• Scenario: Buy one, get one free (100% off).
  • Method: discount_quantity_percentage
  • Logic: repeat|2-100
    
    
• Scenario: Buy 3, get the 4th at 50% off.
  • Method: discount_quantity_percentage
  • Logic: repeat|4-50

single

Also Called: Single Discount, One-Off Discount; or Coupon mode

Description: Unlike the other discount types, the single discount type applies one single discount and not a quantity discount across all products.

Notes: single is the default discount type for coupons, as it makes the most sense in that context. For %/qty and %/$ a single discount type will yield the same discount as allunits.

Examples:

• Scenario: Buy any 5 products, get $10 off your order.
  • Method: discount_quantity_amount
  • Logic: single|5-10

Example Discount Syntax

discount_method=Discount_Name{discount_type|X-A|Y-B|Z-C}

• discount_method: One of the Discount Methods above.
• Discount_Name: The text label applied to the discount and displayed to the customer in the cart. For example, “Summer Special” or “Local Coupon Discount”. A discount name is required for discounts to apply properly on cart pageloads.
• discount_type: A Discount Type from above. Optional. Will default to single if a coupon, or allunits otherwise.
• X, Y, Z: “Discount Tiers”. The threshold at which the Discount Amount will apply.
• A, B, C: “Discount Amounts”. The amount or percentage discount to apply.

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

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

Notes:

• Subscription start and end dates are not currently tied to a store's timezone settings. Test your start and end dates thoroughly or ask in the forum 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.

Notes: 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, 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.

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 indicated the subscription in question (as retrieved from the sub_token) should be cancelled. By “canceling”, the subscription gets a sub_enddate of “tomorrow” (whatever date that may be).

Accepts: true

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

Product option modifiers allow you to modify the price, weight, code, or category when another option is set. Modifiers are placed inside curly brackets ({}) at the end of your product option, and can add to (+), subtract from (-), or set (:) new values to the modified option. Multiple modifiers can be chained together with the “pipe” symbol (|), like value=“S{p+1.50|w-1|c:01a|y:teeny_category}”. When using cart validation it is recommended to set your initial values high then modify down, rather than the other way around. See the validation docs for explanation. Note: if you're working with a product code modifier, be sure your code input comes before your product option that modifies it.

p

Modifies: Price

Increasing: &size=Small{p+5}

Decreasing: &size=Small{p-5}

Setting: &size=Small{p:5}

w

Modifies: Weight. Behaves like the price modifier above.

c

Modifies: Code

Setting: &code=foo&size=Small{c:bar} would yield a code of bar

Appending: &code=foo&size=Small{c+bar} would yield a code of foobar

y

Modifies: Category

Setting: &category=foo&size=Small{y:bar} would yield a category of bar

Notes: This can be especially handy in donation forms that allow both single and recurring donations.