Standard Parameters

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). Limited to 500 characters in length.
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). Limited to 200 characters in length.
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: This parameter can be used when setting up subscriptions, but is stripped from products when they are part of a subscription. In other words, once a product with an expires value is successfully paid for as part of a subscription, it will persist on that subscription indefinitely. 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.

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.
Notes: A single product can have a maximum of 100 custom product options