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.

Transaction Options are not product-specific. Instead, they impact the entire cart or session.

cart

Description: The cart parameter allows for various behaviors to be performed when the cart is requested. Note, these parameters are added after the cart page, like so: /cart?cart=view

Accepts:

• add: The default cart action. If you don't include a cart input, add is assumed.
• view: Displays the cart (if output=html) or returns the cart (if output=json) without adding any products to the cart. Custom session values can be added on a cart=view request.
• checkout: Redirects to the checkout page immediately. Any “add to cart” requests are processed first, so you can add a product to the cart and go immediately to the checkout.
• checkout: With fc_payment_method=amazon_fps Redirects to Amazon for an Amazon FPS checkout immediately. Any “add to cart” requests are processed first, so you can add a product to the cart and go immediately to the checkout. Note that taxes and shipping are not applied, and that it functions differently than a PayPal Express Checkout. Please test this thoroughly before going live with it.
• checkout_paypal_express: Redirects to PayPal for an Express Checkout immediately. Any “add to cart” requests are processed first, so you can add a product to the cart and go immediately to the checkout.
• updateinfo: Redirects to the checkout page with the updateinfo flag set, allowing the customer to update their billing information without actually buying anything. This will empty the customer's cart. More info about the ''updateinfo'' functionality.

Default: view

h:…
(CUSTOM Session Values)

Description: “Session values”, as the name suggests, are added to the customer's session, and are not tied to products. Values stored in session values are available in the JSON, as well as the XML datafeed upon a successful transaction.

Accepts: Any h:name=value pair. The h: prefix on the name makes it a session value as opposed to a custom product option.

Notes: Session values are 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. Or a referrer or affiliate ID could be added to the session and then processed via the XML datafeed upon a completed transaction.

empty

Description: This will clear the contents of the cart. If products are added in the same request, the cart will be emptied and then the products will be added.

Accepts: true

coupon

Description: Adds a coupon code directly to the cart.

Accepts: Any valid coupon code.

Notes: If an invalid code is added, or a code is re-added, an error may display on the cart. As with all coupon codes, once a code is added it will remain for the life of the session or until removed. This can be useful if you want to have a link with a coupon code that doesn't actually add a product to the cart but instead redirects to a order page or the website's homepage. Check the redirect option below for more.

Notes: If you're using the link and form validation, do not sign the coupon value.

redirect

Description: Immediately redirects the user to a page on cart load, such as &redirect=index.html.

Accepts: path/to/file.ext

Notes: For security reasons, the path must be at the store's domain (as entered in the store's FoxyCart settings). ie. You cannot redirect to example.org/path/to/file.ext if your store's domain in FoxyCart is example.com. Additionally, you may need to URL encode any ? and & symbols in a redirection path.

output

Description: Specify the output format for the cart request.

Accepts:

• html
• json (will load the JSON cart object)

Default: html

callback

Description: Used to make an output=json request return a JSONP (instead of JSON) response. This will typically be used with a javascript library like jQuery.

fc_auth_token

Description: Used with Single Sign-On (SSO) to allow a customer to proceed through to the checkout.

If you're considering pre-populating customer info on the checkout you should probably look at using the API and Single Sign-On (SSO) as well, as those two methods will provide more power and flexibility. All of the following values are optional, and can be passed in individually.

customer_email

Notes: Must be a properly formatted email address.

customer_first_name

shipping_first_name

customer_last_name

shipping_last_name

customer_address1

shipping_address1

customer_address2

shipping_address2

customer_phone

shipping_phone

customer_company

shipping_company

customer_city

shipping_city

customer_postal_code

shipping_postal_code

Notes: No validation is performed on values passed in.

customer_state

shipping_state

Notes: Accepts 2-character ISO codes for the state or province of the country determined by the customer's IP address. Because pre-populating the country isn't supported, pre-populating the state/province field only works correctly if the value passed in is valid for the country automatically determined by FoxyCart.

customer_country

shipping_country

x:option_name
__option_name

Description: Any parameter passed to the cart prefixed with an x: or a __ (double underscore) will be entirely ignored by FoxyCart.

Notes: This can be useful if you have “dummy” form fields used only for AJAX purposes or to set hidden inputs.

^^cart^^

Description: This will be replaced with the cart contents.

Notes: Required.

^^store_domain^^

Description: Will be replaced with your FoxyCart store domain. If your store subdomain is mystore then ^^store_domain^^ will be replaced with mystore.foxycart.com. For stores with custom subdomains, it returns the entire custom subdomain, such as secure.example.com.

^^store_name^^

Description: Will be replaced with your store name as setup in your FoxyCart store admin.

^^checkout^^

Description: This will be replaced with the checkout customer form.

Notes: Required.

^^cart^^

Description: This will be replaced with the cart contents.

Notes: While it is not required to have the cart displayed on the checkout, it is generally a good idea to do so.

^^store_domain^^

Description: See the Cart Placeholders section above.

^^store_name^^

Description: See the Cart Placeholders section above.

^^custom_begin^^
^^custom_end^^

Description: If you have custom checkout form fields you would like to include on the checkout page, put them within these two place holders and they will be added to the checkout customer form.

^^multiship_custom_begin^^
^^multiship_custom_end^^

Description: These placeholders are like the ^^custom_begin^^ and _end placeholders above, but are used for per shipto custom fields, when using multi-ship.

Note: the entire receipt template is optional. You can just use the checkout template if you like.

^^receipt^^

Description: This will be replaced with the receipt contents.

Notes: Required. ^^checkout^^ may also be used, and behaves identically to ^^receipt^^.

^^cart^^

Description: See the Cart Placeholders section above.

Notes: Should be considered a required placeholder unless you have a compelling reason to exclude it.

^^store_domain^^

Description: See the Cart Placeholders section above.

^^store_name^^

Description: See the Cart Placeholders section above.

All analytics and order tracking scripts should be placed inside of ^^receipt_only_begin^^ and ^^receipt_only_end^^ tags. If tracking scripts are not placed within these tags they could be loaded multiple times, causing the data collected to be inaccurate.

^^receipt_only_begin^^
^^receipt_only_end^^

Description: Any code placed between these two placeholders will only be loaded once, on the very first load of the receipt. This can be useful if you'd like to include affiliate tracking info or other scripts to systems that might be confused with multiple submissions of identical data. Place all tracking scripts in between these two tags.

^^order_id^^

Description: If you're using an affiliate system like iDevAffiliate, or another analytics app, this place holder might come in handy.

^^subtotal^^

Description: Products subtotal (without tax or shipping).

^^subtotal_with_tax^^

Description: Products subtotal with tax.

^^order_total^^

Description: Order total (including tax and shipping).

^^analytics_google_ga_async^^

Description: Outputs the full _addTrans(), _addItem(), and _trackTrans() for the asynchronous Google Analytics approach, outlined here.

^^analytics_google_ga^^

Description: “New” version of Google Analytics (ga.js). Details.

^^analytics_google_urchin^^

Description: “Old” version of Google Analytics (urchin.js). Details.

Note: Deprecated. This placeholder will be removed in a future version.

All of the following placeholders have separate outputs for HTML and text based emails. Some of what these placeholders output can be modified in the “language” section of your FoxyCart admin.

^^receipt^^

Description: This will be replaced with data from the transaction such as the billing address, shipping address (if different than billing), custom fields, order ID, order date, and order total.

Notes: ^^checkout^^ may also be used, and behaves identically.

^^cart^^

Description: This will be replaced with the cart contents.

Notes: This placeholder also includes subscription-specific links and information (overridable in the “language” section of your FoxyCart store), allowing for cancellation and transfer of subscriptions.

^^order_id^^

Description: This will be replaced with the transaction ID.

^^receipt_url^^

Description: The URL to the revisitable receipt, for future reference.

^^store_domain^^

Description: See the Cart Placeholders section above.

^^store_name^^

Description: See the Cart Placeholders section above.

^^store_logo^^

Description: Will be replaced with your store logo as configured in your FoxyCart store admin (it includes an img tag as well – not just the url).

^^order_begin^^
^^order_end^^

Description: Anything placed inside of these placeholders will only be included if the receipt email is for an order, and not for an update_info or sub_cancel (subscription cancellation).

^^subscription_cancel_begin^^
^^subscription_cancel_end^^

Description: Any code placed between these two placeholders will only be included if and only if the email being sent is to confirm a subscription cancellation (ie. sub_cancel=true).

Notes: The default receipts include an example of how these placeholders can be used.

^^subscription_modification_begin^^
^^subscription_modification_end^^

Description: Any code placed between these two placehoders will only be included if and only if the email being sent is for a subscription being modified (but not cancelled). This block will not be included for the automatic subscription processing that occurs; only when the sub_token is used in a manually processed transaction.

^^sub_token_url^^

Description: Will be replaced with the sub_token URL.

Notes: This can be used to create links to allow customers to easily transfer cancel a subscription. See the “language” section of your FoxyCart admin for examples of how this is used.

^^updateinfo_begin^^
^^updateinfo_end^^

Description: Anything placed inside of these placeholders will only be included if the receipt email is for an update_info request (and not a normal transaction or a subscription cancellation).