Documentation You are here: start » v » 2.0 » cheat_sheet

FoxyCart Cheat Sheet: Product and Cart Parameters

Product Parameters

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.
  • Case sensitivity: Product parameters are case sensitive.

Standard Product Options

name
Description: The name of the product that will be displayed in the cart.
Accepts: Any characters. Limited to 255 characters in length.
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.
Multi-currency: Optionally accepts a 3-character ISO currency code appended to the numeric portion. More details here.
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).
Examples: &image=http://example.com/path/to/image.jpg, &image=local/path/to/image.png, <input type=“hidden” name=“image” value=“http://example.com/path/to/image.jpg”>
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 200 characters in length.
Example: &code=ISBN 978-0-12-345678-9
Notes: Required if using Link and Form Validation. Not required otherwise.
parent_code
Description: Parent item code. Used if this should be a child product in a bundle.
Accepts: Any characters. Limited to 200 characters in length.
Example: &parent_code=bundle7734
Notes: There are some special requirements for this field if using Link and Form Validation. If you set quantity_min=1, the child product will be locked to the parent product and won't be able to be deleted by itself or have it's quantity changed independently.
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.
expires
Description: Allows you to sell products which are only available for purchase before a certain date or for a limited time. You can pass in a number of minutes or a timestamp in the future at which point the product will be removed from the cart. An informational message will be displayed when the order contains a product which will expire within 15 minutes.
Accepts: number, either in minutes or a timestamp based on FoxyCart server time (currently PST)
Example: &expires=15 (expires in 15 minutes) or &expires=1593583199 (expires a second before midnight, June 30th 2020).
Notes: You can find many tools online for creating timestamps which may be helpful here. If the checkout is submitted with an expired product, the customer will be shown an error and told that an expired product has been removed from the cart. After adding, an expires parameter is set against the product details in the cart JSON object representing the time that it will expire as an epoch timestamp (in seconds). Currently, using an expires value representing time in minutes will cause the same product to be treated as a unique in the cart. Specifying as a timestamp will keep them unified.
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.
Accepts: Any characters. Custom name attribute limited to 100 characters and the value is limited to 1024 characters.

Product Discounting Options

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

Discount Methods

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.

Discount Types

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

Discount Syntax

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.

Subscription Product Options

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. For a relative date from today, you can also specify an integer followed by a single character denoting the unit of time.
  • YYYYMMDD = Example: 20150131 = January, 31 2015.
  • 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.
  • 60d = 60 days from today.
  • 2w = 2 weeks from today. For date calculations, 1w = 7d.
  • 1m = 1 month from today.
  • 1y = 1 year from today.
Notes:
  • This is an optional field. Not indicating a “sub_startdate” would automatically assign it its default value.
  • 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. For a relative date from today, you can also specify an integer followed by a single character denoting the unit of time.
  • YYYYMMDD = Example: 20150131 = January, 31 2015.
  • 60d = 60 days from today.
  • 2w = 2 weeks from today. For date calculations, 1w = 7d.
  • 1m = 1 month from today.
  • 1y = 1 year from today.
Notes:
  • This is an optional field. Not indicating a “sub_enddate” would make the subscription run indefinitely.
  • 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, 2015 that is supposed to run for six months and then stop, set sub_endate to 20150602 (June 2nd, 2015) 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

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. Modifiers cannot be applied to standard product options (ie: price or name).

p
Modifies: Price
Increasing: &size=Small{p+5}
Decreasing: &size=Small{p-5}
Setting: &size=Small{p:5}
Notes: If working with multicurrency, you may need to append the currency code to the price as required, such as {p+5CAD}. If no currency code is specified, it's assumed the price is in the store currency.
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 (Non-Product Specific) Options

Transaction Options are parameters included within cart requests that are not product-specific. Instead, they impact the entire cart or session. In the same way as the Product Options above, Transaction Options are included within the cart request, either as an additional parameter in the add to cart link, or as an input within a form.

cart
Description: The cart parameter allows for various behaviors to be performed when the cart is requested. Note, the cart parameter is separate from the /cart portion of the cart URL. Within an add to cart link it should be separate like /cart?cart=view, or specified as a hidden input in an add to cart form.
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=paypal_ec Redirects to PayPal Express Checkout with reference transactions 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_paypal_express: Redirects to PayPal for the legacy 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.
  • empty: Deprecated. Will be removed in a future release. Use the empty parameter instead.
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: Empties the cart, including all custom session values, coupons, customer address and prepopulation values, shipping selections, etc.
  • reset: Does all of the above but also resets the cookie. The use case for this is uncommon, so in general you should use the true instead of the reset value.
coupon
Description: Adds one or more coupon codes directly to the cart.
Accepts: Any valid coupon codes, separated by a comma.
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.
locale
Experimental Functionality: This feature will be further tested and documented. Please refer to FoxyCart's multicurrency documentation for more info.
Description: Sets the currency for the cart. Converts any existing items in the cart from the current currency (the store's default) to the newly specified currency.
Accepts: FoxyCart will attempt to match a locale in the following order. If no locale is matched, it will continue to the next option and attempt a match there.
  1. A full locale code in the format of 2 character language code, followed by an underscore and a two character territory, such as en_US (US, English) or es_MX (Mexico, Spanish).
  2. A value prefixed by the h:lang value: Whatever you pass through as the locale value will be prefixed with the value currently set in h:lang, concatenated with an underscore. So if you have set h:lang=es and pass through locale=MX, the session will attempt to set the locale to es_MX.
  3. A value prefixed by en_: If the above don't match, the locale value will be prefixed with en_ in an attempt to match a valid locale.
  4. Case-insensitive locale match
Notes: Changing the locale will empty the cart of its products. Products added in the same request will work fine, however.
template_set
Description: Used to specify a specific template set to apply to this cart session
Accepts: Any valid template set code
Notes: If a template set is applied which changes the locale of the cart session, any existing products will be removed from the cart. Products added in the same request will be added normally.
output
Description: Specify the output format for the cart request.
Accepts:
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.
h:shipto_residential
Description: Since shipping rates can be returned from the cart (where the company address field isn't entered), and since the difference between residential and commercial shipping rates can be important, you can set this to true or false to override the setting from the shipping section of the FoxyCart admin.
Accepts: true or false
Default: n/a. Shipping rates are determined in the shipping settings in the FoxyCart admin.
h:bypass_maintenance_mode
Description: You can set this to true to override the maintenance mode for your store (and view the checkout normally).
Accepts: true
Default: false
utm_source, utm_medium, utm_campaign, utm_term, utm_content
Description: URL parameters for Google Analytics custom campaigns. When specified as part of an add to cart, they'll be included in the next page load of either the cart or the checkout.
Notes: These values should not be encrypted when using link/form encryption, and they must be passed as URL parameters - passing them within the hash is not supported. The values are not stored in the session at all - they're just used on the resulting page load of the add to cart action.

Customer Information Pre-Population

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.
billing_first_name
shipping_first_name
billing_last_name
shipping_last_name
billing_address1
shipping_address1
billing_address2
shipping_address2
billing_phone
shipping_phone
billing_company
shipping_company
billing_city
shipping_city
billing_postal_code
shipping_postal_code
Notes: No validation is performed on values passed in.
use_different_addresses
Notes: In order to pass in both shipping and billing information, this must also be passed in with a value of 1 so the checkbox on the checkout will be properly checked to display both the billing and shipping information.
billing_region
shipping_region
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.

Excluding Options

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.

View Data

FoxyCart uses twig and twig.js as a template language so you can completely customize everything about your checkout experience. Listed below is all the data which is exposed to the templates and also available in JavaScript in the FC.json variable.

Cart

cart_cancel_and_continue_link
Description: URL for continuing back to the store from the cart.
cart_config_hash
Description: Used to validate the locale storage version of FC.json.config is up to date.
cart_is_fullpage
Description: true or false depending if the cart is the full page cart or not
context
Description: Either cart, checkout or receipt. Used for configuring various display and functionality concerns. cart represents both Sidecart and full page cart versions.
coupons
coupons.{coupon_code}
coupons.{coupon_code}.amount
coupons.{coupon_code}.id
coupons.{coupon_code}.is_applied
coupons.{coupon_code}.name
Description: Coupons associated with this cart. The {coupon_code} is the code value used by the customer to add the coupon.
custom_fields
custom_fields.{name}
custom_fields.{name}.is_hidden
custom_fields.{name}.value
Description: The custom fields associated with this transaction. The is_hidden bit will be true if the custom fields were passed in via the h: prefix. The {name} is the value of the name assigned to this custom field.
expires_in
Description: The time in seconds until the first product in the cart expires
future_coupons
future_coupons.{coupon_code}
future_coupons.{coupon_code}.amount
future_coupons.{coupon_code}.id
future_coupons.{coupon_code}.is_applied
future_coupons.{coupon_code}.name
Description: Same as coupons above, but for products with a start date or next transaction date in the future.
future_subscription_totals_by_date
future_subscription_totals_by_date.total
future_subscription_totals_by_date.total_item_price
future_subscription_totals_by_date.total_shipping
future_subscription_totals_by_date.total_tax
future_subscription_totals_by_date.total_weight
Description: The totals for subscription products with a start date or next transaction date in the are grouped together here for the cart display.
has_eligible_coupons
Description: If the cart contains products which can have a coupon applied to them.
has_future_products
Description: If the cart contains products with a start date or a next transaction in the future (a “future product”).
has_future_shipping
Description: If the cart contains future products from categories which support shipping.
has_live_rate_shippable_products
Description: If the cart contains products from categories which support live shipping rates.
has_location_dependant_taxes
Description: If the cart contains products from categories which have taxes based on the customer's location. This is used for handling third party payment options such as PayPal Express and Amazon FPS.
has_multiship
Description: If the store has multiship turned on.
has_product_images
Description: If any of the products in the cart took advantage of the image option.
has_shippable_products
Description: If the cart contains products from categories which support shipping.
has_subscriptions
Description: If the cart contains subscription products.
has_taxes
Description: If the cart contains products from categories which have taxes applied to them.
is_future_shipping_only
Description: If all of the products in the cart are future products, this tells the system the shipping calculations will only be for future products.
is_new_subscription
Description: If the cart contains a new subscription
is_subscription_cancel
Description: If this transaction is for canceling an existing active subscription.
is_subscription_modification
Description: If this transaction is currently modifying an existing active subscription. This will usually mean there are products in the cart which will charge in the future.
is_updateinfo
Description: If cart=updateinfo.
item_count
Description: The sum total of all the product quantities in the cart.
items[]
Description: An array of all the products in the cart.
items[].alt_name
Used in the alt attribute of the product link.
items[].base_price
Product price before product option modifiers.
items[].category
Product category code.
items[].code
Product code or sku.
items[].delivery_type
The delivery type of this product.
items[].downloadable_id
If this product is a downloadable, this is the downloadable id for it.
items[].expires
The timestamp for when this product expires.
items[].height
Reserved for future use.
items[].id
Unique internal id for this product.
items[].image
The image url for this product.
items[].is_parent
If this product is a parent product or not
items[].item_number
Used for organizing item display and managing the product update process.
items[].length
Reserved for future use.
items[].multiship
The multiship group number used for organizing products into shipments.
items[].name
The product name.
items[].options[]
Description: Array or product options for this product.
items[].options[].class
The option name stripped of anything but letters, numbers, dashes and underscores so it can be used as a html class attribute.
items[].options[].name
The product option name.
items[].options[].value
The product option value.
items[].price
The price extension of these products (price_each * quantity)
items[].price_each
The actual price of an individual product after product option modifiers.
items[].quantity
The quantity of this product in the cart.
items[].quantity_max
The maximum quantity allowed in the cart for this product.
items[].quantity_min
The minimum quantity allowed in the cart for this product.
items[].shipto
The shipto name of this product used for multiship.
items[].sub_enddate
The end date of this subscription product.
items[].sub_frequency
The frequency of this subscription product.
items[].sub_nextdate
The next date this subscription product will process.
items[].sub_startdate
The start date of this subscription product.
items[].url
The url of this product.
items[].weight
The weight extension of the this product (weight_each * quantity)
items[].weight_each
The weight of an individual product.
items[].width
Reserved for future use.
loading_coupons
loading_quantity
loading_shipping_results
loading_taxes
Description: Used for determining if a loading animation should currently be displayed.
locale_code
Description: The locale code for this cart such as en_US
locale_info
Description: This includes all of the data output by PHP's localeconv() including currency symbols, decimal point character, and thousands separator.
messages
Description: Used for displaying error, warning, and information messages in the cart.
messages.errors[]
Description: An array of error messages.
messages.errors[].context
The context of this error message which often relates to a form input.
messages.errors[].message
The content of the error message. Often times this will be blank as the error message is directly part of the template as a language string.
messages.info[]
Description: An array of informational messages.
messages.info[].context
The context of this informational message.
messages.info[].message
The content of the informational message.
messages.warnings[]
Description: An array of warning messages.
messages.warnings[].context
The context of this warning message.
messages.warnings[].message
The content of this warning message.
multiship_data
Description: (Currently empty for the cart, may be added in the future)
payment_info_required
Description: True if payment information is required for this transaction (order total > 0 for an order and not doing a subscription cancel).
session_id
Description: The session id of this cart.
session_name
Description: The name of the FoxyCart session.
shipping_address
Description: Container for the shipping address information.
shipping_address.address1
Address 1
shipping_address.address2
Address 2
shipping_address.address_name
The address name of this address (used mainly for multiship)
shipping_address.city
City
shipping_address.city_option_selected
The city, region put togther as a string used in the select option.
shipping_address.city_options
Description: Array of options returned from the postal code lookup.
shipping_address.city_options.city
City
shipping_address.city_options.region
Region (such as state or province)
shipping_address.company
Company
shipping_address.country
Two character country code
shipping_address.country_name
Country name
shipping_address.first_name
First Name
shipping_address.last_name
Last Name
shipping_address.phone
Phone
shipping_address.postal_code
Postal code
shipping_address.prefix
Prefix (used for multiship)
shipping_address.region
State or Province code
shipping_address.region_label
Label for this region (such as state or province)
shipping_address.region_name
State or province name.
shipping_address.shipping_results[]
Description: A result of calculating live shipping rates.
shipping_address.shipping_results[].method
This shipping method (USPS, UPS, FedEx, etc).
shipping_address.shipping_results[].price
The quoted price for this shipping service.
shipping_address.shipping_results[].service_id
The service id used by this shipping method for this service.
shipping_address.shipping_results[].service_name
The name of this shipping service.
shipping_address.shipping_service_description
The description of this shipping service.
shipping_address.shipping_service_id
The shipping service id the service the customer selected.
shipping_address.taxes[]
Description: An array of taxes associated with this shipping address.
shipping_address.taxes[].amount
Amount of this tax.
shipping_address.taxes[].applies_to_handling
Whether or not this tax applies to handling fees.
shipping_address.taxes[].applies_to_shipping
Whether or not this tax applies to shipping costs.
shipping_address.taxes[].default_amount
The default amount before being applied to a specific location.
shipping_address.taxes[].is_error
If this tax has an error.
shipping_address.taxes[].is_live
If this tax is live.
shipping_address.taxes[].name
The name of this tax.
shipping_address.taxes[].rate
The tax rate.
shipping_address.taxes[].tax_id
The internal id of this tax.
shipping_address.total_future_shipping
The total amount of future shipping costs for the products being sent to this address.
shipping_address.total_shipping
The total shipping costs for the products being sent to this address.
shipping_address.total_tax
The total tax for the products being sent to this address.
shipping_address.type
The type for this address (either billing or shipping)
shipping_and_handling_label
Description: The label describing the shipping applied to this order.
show_address_entry
Description: Used to determine if the cart address entry form should be displayed.
show_amazon_fps_payment_option
Description: Used for determining if the amazon payment button should be shown. It will not be shown if there are subscriptions in the cart.
show_coupon_input_button
Description: Used for determining if the coupon input button should be shown.
show_multiship_details
Description: Used to toggle the multiship details.
show_paypal_express_payment_option
Description: Used for determining if the Paypal payment button should be shown.
show_shipping_tbd
Description: Used for determining if live shipping rates haven't yet been calculated so a “TBD” indicator is displayed instead.
store_id
Description: The FoxyCart store id for this store.
template_set
Description: The code for the cart's current template set
total_discount
Description: The total coupon discount applied to this transaction.
total_future_item_price
Description: The total price of the future items in the cart.
total_future_shipping
Description: The total amount of the shipping costs assigned to future products in the cart.
total_future_weight_shippable
Description: The total weight of the future shipable products in the cart.
total_item_price
Description: The total price of the items in the cart.
total_order
Description: The order total
total_shipping
Description: The shipping total
total_tax
Description: The tax total
total_weight
Description: The total product weight.
total_weight_shippable
Description: The total weight of the shippable products in the cart.
transaction_id
Description: The FoxyCart transaction id for the contents of the cart.

Cart Config (FC.json.config)

cache_path
Description: Path used for caching images in the FoxyCart system.
cart_config_hash
Description: Used to validate the locale storage version of FC.json.config is up to date.
cdn_base_path
Description: The base path of your store's files served via the CDN.
cdn_static_path
Description: The base path of static files served via the CDN.
css_file
Description: The full path to the versioned store-specific stylesheet served by the CDN.
currency_format
Description: The currency format configured for your store and use for twig money formatting.
lang
Description: All language strings in FoxyCart are completely customizable. We start with a base language configuration and then you can customize them individually from there.
lang.{code}
lang.{code}…
Description: You can view all language strings used on the cart by viewing FC.json.config.lang in your browser's web console.
locations
Description: A complete listing of all valid country codes and state/provinces within those countries used by our find-as-you type auto complete (FoxyComplete) country and region lookup system.
locations.{country_code}
locations.{country_code}…
Description: Locations are grouped by their 2 character ISO country code.
locations.{country_code}.active
If this country is actively being used by the FoxyComplete system.
locations.{country_code}.alt
Alternative spellings or local spellings of this location name.
locations.{country_code}.boost
Used to give certain spellings a boost over others.
locations.{country_code}.cc2
ISO 3166-1 alpha-2 code for this country.
locations.{country_code}.cc3
ISO 3166-1 alpha-3 code for this country.
locations.{country_code}.ccnum
ISO 3166-1 numeric code for this country.
locations.{country_code}.cn
Country name (currently in english).
locations.{country_code}.pc
Description: Postal Code format details.
locations.{country_code}.pc.int
If the postal code is numeric only.
locations.{country_code}.pc.lang
The language key string for the description of this postal code.
locations.{country_code}.pc.regex
The regex pattern this postal code fits in for validation purposes.
locations.{country_code}.pc.req
Whether or not the postal code is required.
locations.{country_code}.pc.search
Whether or not this country supports a postal-code based search.
locations.{country_code}.r
Description: Region details for this country.
locations.{country_code}.r.lang
The language key string for name of this country's regions such as “state.”
locations.{country_code}.r.options.{region code}
Description: Region information organized by two character ISO code.
locations.{country_code}.r.options.{region code}.active
If this region is actively being used by the FoxyComplete system.
locations.{country_code}.r.options.{region code}.alt
Alternative spellings or local spellings of this region name.
locations.{country_code}.r.options.{region code}.boost
Used to give certain spellings a boost over others.
locations.{country_code}.r.options.{region code}.c
ISO 3166-1 alpha-2 code for this country.
locations.{country_code}.r.options.{region code}.n
Region name (currently in english).
locations.{country_code}.r.options.{region code}.req
If regions are required for this country.
locations_billing
Description: Locations used for billing address information only (see locations)
locations_shipping
Description: Locations used for shipping address information only (see locations)
paypal_checkout_button_url
Description: Locale specific PayPal payment button URL.
post_url
Description: URL for posting cart and checkout forms.
store_domain
Description: This FoxyCart stores FoxyCart store domain (the example part of example.foxycart.com).
store_logo_url
Description: Your store logo url as configured in the FoxyCart admin.
store_name
Description: Your FoxyCart store name as configured in the FoxyCart admin.
store_url
Description: Your store's website URL as configured in the FoxyCart admin.
template_config
Description: All of the settings configured in the FoxyCart admin under the configuration menu will be available here for you to use within your twig template customizations.
template_config.analytics_config
Description: (UNDER CONSTRUCTION): A place to automatically configure your analytics tools.
template_config.analytics_config.google_analytics
Description: Configuration settings for your Google Analytics account.
template_config.analytics_config.google_analytics.account_id
Your Google Analytics acccount id
template_config.analytics_config.google_analytics.account_key
Your Google Analytics acccount key
template_config.analytics_config.google_analytics.usage
Configuration for how this setting is being used.
template_config.analytics_config.segment_io
Description: Configuration settings for your Segment.io account.
template_config.analytics_config.segment_io.account_key
Your Segment.io acccount key
template_config.analytics_config.segment_io.usage
Configuration for how this setting is being used.
template_config.analytics_config.usage
Configuration for how this setting is being used.
template_config.cart_display_config
Description: Settings for controlling the display details of your cart.
template_config.cart_display_config.show_product_category
Whether or not to show the product category code in the line item details.
template_config.cart_display_config.show_product_code
Whether or not to show the product code in the line item details.
template_config.cart_display_config.show_product_options
Whether or not to show the product options in the line item details.
template_config.cart_display_config.show_product_weight
Whether or not to show the product weight in the line item details.
template_config.cart_display_config.usage
Whether or not the cart display config has been set or if defaults are in use.
template_config.checkout_type
Description: Either default_account, default_guest, guest_only, or account_only for determing if your checkout will accept guest checkouts or required named accounts and which one will be the default action.
template_config.colors
Description: This configuration allows you to specify the main colors of your website and our system will adjust the CSS using SASS as needed to incorporate your colors into our template designs.
template_config.colors.primary
colors.secondary
colors.tertiary
The primary, secondary, and tertiary colors for your website.
template_config.colors.usage
Whether or not this configuration setting is being used.
template_config.csc_requirements
Description: Settings for how you'd like to require the Card Security Code (CSC) for your website. Values include all_cards, sso_only (Single Sign On only), new_cards_only (do not require for saved cards).
template_config.custom_checkout_field_requirements
Description: Configuration for displaying and requiring various checkout fields and features.
template_config.custom_checkout_field_requirements.billing_address1
template_config.custom_checkout_field_requirements.billing_address2
template_config.custom_checkout_field_requirements.billing_city
template_config.custom_checkout_field_requirements.billing_company
template_config.custom_checkout_field_requirements.billing_country
template_config.custom_checkout_field_requirements.billing_first_name
template_config.custom_checkout_field_requirements.billing_last_name
template_config.custom_checkout_field_requirements.billing_phone
template_config.custom_checkout_field_requirements.billing_postal_code
template_config.custom_checkout_field_requirements.billing_region
These can be set to either hidden, required, optional, or default (in the case of billing_region)
template_config.custom_checkout_field_requirements.cart_controls
Whether or not to allow cart controls on the checkout page.
template_config.custom_checkout_field_requirements.coupon_entry
Whether or not to allow the coupon entry form on the checkout page.
template_config.custom_config
Description: This is where you can put your own custom configuration values for your twig templates. This might be helpful if you want to hard code your templates with some logic and change the display outcome by just adjusting the values here.
template_config.custom_script_values
Description: Used for setting custom JavaScript or CSS elements to be used in the default template.
template_config.custom_script_values.footer
If you have custom JavaScript you'd like to add above the </body> tag for your cart, checkout and receipt templates, put that here. You can use it for conversion tracking scripts by checking the first_receipt_display variable. Full twig syntax is supported here.
template_config.custom_script_values.header
If you have custom CSS (or JavaScript, though the footer is a better place for that) you'd like to add to the <head> tag for your cart, checkout and receipt templates, put that here. Full twig syntax is supported here.
template_config.custom_script_values.checkout_fields
If you to add custom fields to your store's checkout template, add HTML here. These will be inside the <form> tag on the checkout page and will submit with the rest of the checkout form and be recorded as custom fields on the transaction. Full twig syntax is supported here.
template_config.debug
Description: Turn this on to see debugging output in your web browser's console log.
template_config.debug.usage
How this setting is currently being used.
template_config.foxycomplete
Description: Our country and region auto completion system which lets users find locations as they type instead of having to select from a huge list of options.
template_config.foxycomplete.combobox_close
The icon used for closing the location combo box.
template_config.foxycomplete.combobox_open
The icon used for opening the location combo box.
template_config.foxycomplete.show_combobox
Whether or not to show the location combo box.
template_config.foxycomplete.show_flags
Whether or not to show the country flags.
template_config.foxycomplete.usage
Configure how this feature is being used.
template_config.newsletter_subscribe
Description: This allows you to easily add a “Subscribe Me” checkbox to your checkout template so you can use that value as a custom field in the transaction datafeed later.
template_config.newsletter_subscribe.usage
How this setting is configured.
template_config.ssl_receipt
Description: If you require the receipt page to be loaded over HTTPS, turn this feature on.
template_config.supported_payment_cards
Description: An array of the accepted payment cards by your store such as Visa, MasterCard, etc. This will control which card logos are shown on the checkout page.
template_config.tos_checkbox_settings
Description: Use this setting to easily add a terms of service checkbox to your checkout page.
template_config.tos_checkbox_settings.initial_state
Whether or not the terms of service checkbox is checked by default.
template_config.tos_checkbox_settings.url
The URL to your terms of service document.
template_config.tos_checkbox_settings.usage
How this setting is configured (none, required or optional).
template_config.use_checkout_confirmation_window
Description: (UNDER CONSTRUCTION) A popup window for customers to confirm their order before submitting it.
template_config.use_checkout_confirmation_window.usage
Configure how this feature is being used.
weight_uom
Description: The unit of measure used for calculating shipping weights.
with_controls
Description: Whether or not the current display output includes cart controls such as quantity and coupon entry fields.

Checkout

The checkout view data in FC.json includes everything in the cart including the following values:

anonymous_checkout_selected
Description: Used for determing if a customer opted to check out anonymously.
auth_token_is_valid
Description: Used for determining if the Single Sign On (SSO) authorization token is valid.
authentication_is_in_progress
Description: If the customer is currently authenticating.
authentication_is_not_successful
Description: If customer authentication failed.
authentication_is_successful
Description: If customer authentication is successful.
billing_address
Description: (See cart shipping_address)
cc_cvv2
Description: Credit card Card Security Code for new cards.
cc_cvv2_saved
Description: Credit card Card Security Code for existing cards.
cc_exp_month
Description: Credit card expiration date month.
cc_exp_year
Description: Credit card expiration date year.
cc_number
Description: Credit card number.
cc_number_masked
Description: Masked credit card number.
cc_type
Description: Credit card type (Visa, MasterCard, Amex, etc)
change_password
Description: If the customer as opted to change their password.
checkout_date
Description: The date this checkout took place.
checkout_type
Description: The type of checkout taking place which can be either default_account, default_guest, guest_only, account_only
continue_url
Description: The URL used on the receipt to continue back to your store's website.
create_account
Description: Whether or not the customer chose to create an account during checkout.
customer_email
Description: The customer email address.
customer_id_encoded
Description: Used for determining which customer just logged in.
customer_is_authenticated
Description: Used for determining if the current customer is authenticated via Single Sign On (SSO).
customer_password
Description: The customer password entered by the user.
email_is_checking
Description: If the checkout is currently checking to see if the email address given belongs to an existing customer.
email_is_found
Description: Indicates if the email address given belongs to an existing customer.
email_is_valid
Description: Indicates if the email address given is valid.
fc_auth_token
Description: The Single Sign On (SSO) authentication token.
fc_customer_id
Description: The Single Sign On (SSO) passed in customer id.
first_receipt_display
Description: If the receipt is being displayed for the very first time which can be helpful for displaying specific conversion tracking code.
force_password_reset
Description: If the customer requires a password reset because they logged in with a temporary password.
force_saved_account
Description: If the cart contains subscriptions, the customer will be forced to checkout as a named account.
geoip
Description: Used in the emails sent to store administrators to display the GEO IP lookup details for the country based on the ip address of the customer checking out. This will not be available for the checkout or receipt context.
has_discounts
Description: If the cart contains coupon discounts.
has_downloadables
Description: If the cart contains downloadable products.
has_saved_cc
Description: If the customer has a saved credit card.
has_visible_custom_fields
Description: If the checkout has custom fields which are not hidden custom fields.
hosted_payment_gateways
Description: Array of hosted payment gateways available for this checkout.
hosted_payment_gateways.lang_pay_with
Language and logo used on the checkout page to tell the customer they can pay with this method.
hosted_payment_gateways.lang_payment_method
Additional information for the customer indicating what happens next, such as if they will be redirected to another site to confirm payment.
hosted_payment_gateways.supports_subscriptions
Wehther or not this hosted payment method supports subscriptions.
hosted_payment_gateways.type
The type of this hosted solution such as bitpay, dwolla, etc.
html_downloadable_links
Description: The links for downloading products purchased as FoxyCart downloadables.
ip_address
Description: The ip address of the customer.
is_anonymous
Description: If the customer checked out as an anonymous user.
is_uoe
Description: If the customer is currently logged in using Unified Order Entry.
loading_submit
Description: Used for determining if an animation should be displayed near the submit button.
multiship_data
Description: Array of shipments for each multiship customer shipment (in additiona to address data found in shipping_address)
multiship_data.address_name
The name given to this shipto address. This will be the same as the “shipto” value in the cart.
multiship_data.checkout_total_tax
The tax total for this shipment used during checkout.
multiship_data.custom_fields
Custom fields for this shipment.
multiship_data.has_live_rate_shippable_products
Whether or not this shipment has products from a category which uses live shipping rates.
multiship_data.has_shipping_or_handling_cost
Whether or not this shipment has products from a category which has any shipping or handling costs.
multiship_data.has_visible_custom_fields
Whether or not any of the custom fields in this shipment are visable.
multiship_data.number
The shipto number used for visual organization.
multiship_data.total_future_shipping
The total future shipping amount in this shipment
multiship_data.total_item_price
The total amount of all the items in this shipment
multiship_data.total_price
The total price in this shipment
multiship_data.total_shipping
The total shipping amount in this shipment
multiship_data.total_tax
The total tax amount in this shipment
new_customer_password
Description: When creating a new customer or changing an existing password, this will contain the new password entered by the customer.
order_id
Description: The transaction id of this order.
password_expired
Description: True if the password this customer used has expired, such as when using a temporary password.
payer_id
Description: Used by 3D Secure systems.
payment_is_pending
Description: If the customer checked out with a hosted gateway which first marks the payment as pending, this boolean can be used for special messaging to the customer on the receipt.
payment_method_type
Description: Either plastic_saved, plastic_new, or the type of the hosted payment gateway being used.
payment_type
Description: The payment type usually being plastic, hosted (as in a hosted payment gateway), purchase_order, paypal or other.
processor_response
Description: The payment gateway response value used on the receipt.
purchase_order
Description: The purchase order value submitted by the customer.
receipt_url
Description: The connonical url of the transaction receipt.
required_fields
Description: Array of required field names as configured in the FoxyCart admin template configuration page.
shipping_and_handling_label
Description: The default label for the shipping and/or handling fees charged for this order.
show_message_for_testing
Description: Used to indicate if a testing informational message is to be displayed. This can be useful for styling purposes and can be triggered by passing in a fc_show_info custom field.
status
Description: Used in some situations such as with hosted gateways to specify the status of the current transaction. Values include approved, authorized, declined, pending, or rejected.
subscriptions
Description: Array of subscription data for this transaction.
subscriptions.description
The textual description of this subscription including the frequency.
subscriptions.sub_token_url
The subscription token url which can be used by the customer to modify or cancel this subscription or by the store to adjust the subscription via the API.
subscriptions.html_links
The links needed by the customer to modify or cancel this subscription in html format.
subscriptions.text_links
The links needed by the customer to modify or cancel this subscription in text format.
temporary_password_sent
Description: Indicating of the temporary password has been sent to the customer.
text_downloadable_links
Description: Text links for downloading the products purchased.
timestamp
Description: Used by the Single Sign On (SSO) feature to ensure the token is only valid for a specific amount of time.
token
Description: Used by 3D Secure systems.
tos_agreement
Description: The state of the terms of service checkbox, if being used by the checkout.
use_alternate_shipping_address
Description: A boolean state of the checkbox for using an alternate shipping address other than the billing address.
use_different_addresses
Description: The state of the checkbox for using an alternate shipping address other than the billing address.
utils
Description: Custom twig macros we've added which we've also ported to twig.js
utils.get_error_string
Get a specific error string from the array of errors by context key.
utils.get_info_string
Get a specific info string from the array of informational strings by context key.
utils.shipping_results
Macro for formatting shipping rate results into radio buttons.
utils.use_different_addresses
Macro for displaying the use alternate address checkbox.

Checkout Config (FC.json.config)

The checkout config view data in FC.json.config includes everything in the cart including the following values:

alert_test_gateway
Description: Used for FoxyCart test stores.
base_directory
Description: Used for determing the correct base directory for this store version.
cc_expiration_months
Description: An array of months for displaying the credit card expiration month select box.
cc_expiration_years
Description: An array of years for displaying the credit card expiration year select box.
has_multiple_payment_options
Description: A boolean used for display logic when there are more than one payment options enabled by the store for the checkout page.
lang
Description: Includes language strings from cart config lang as well as additional strings for checkout, email and receipt contexts.
supports_pay_with_plastic
Description: A boolean used for display logic on the checkout page for if the store supports paying with a debit or credit card.
supports_purchase_order
Description: A boolean used for dispaly logic on the checkout page for if the store supports paying by purchase order.

Email

The email view data in FC.json.config includes everything in the cart and checkout including the following values:

days_since_first_failed_transaction
Description: The number of days since the subscription in this email first failed, used for dunning reminder emails.
is_order
Description: If this email is for a normal transaction
is_subscription_dunning_cancellation
Description: If this email is for a subscription that has just been cancelled through the dunning functionality
is_subscription_dunning_reminder
Description: If this email is for a subscription past due reminder email triggered by the dunning functionality

Site Tools