Differences

This shows you the differences between two versions of the page.

--- v:0.7.0:cheat_sheet [2011/02/19 21:03] – [Transaction (Non-Product Specific) Options] foxyluke
+++ v:0.7.0:cheat_sheet [2017/06/27 18:52] (current) – [Subscription Product Options] marija
@@ Line 1: / Line 1: @@
 ====== FoxyCart Cheat Sheet: Product and Cart Parameters ======
-===== Standard Product Options =====
+===== Product Parameters =====
+==== Standard Product Options ====
   ; ''name''
@@ Line 13: / Line 15: @@
   : **Example:** ''&price=9.99''
   : **Notes:** <wrap round important>Required.</wrap>
-  ; ''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'', ''&images=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.
   ; ''code''
   : **Description:** Item code. Can be used however you’d like (internal use, product SKU, etc.).
@@ Line 30: / Line 27: @@
   : **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 cart, //per product, per cart//.
+  : **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 //indentical//. 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 cart, //per product, per cart//.
+  : **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 //indentical//. 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.
+  : **Notes:** This attribute, like all others, relies on the products in the cart being //indentical//. 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.
@@ Line 44: / Line 41: @@
   : **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:**  <wrap round important>Supports up to a maximum of three decimal places.</wrap>
   ; ''shipto''
   : **Description:** Allows you to specify specific ship-to address labels for each cart add.
@@ Line 53: / Line 51: @@
   : **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:** <wrap important>All product options must be prefixed</wrap> in order for grouping to happen, and all required options are still required //per product//.
+  : **Example:** <code html>
+<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>
+</code>
   ; CUSTOM Product Options
   : **Description:** <wrap round tip>You may add any additional attributes to any product you’d like.</wrap> 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.
-===== Product Discounting Options =====
+==== Product Discounting Options ====
 Please see [[.:coupons_and_discounts|Coupons and Discounts]] for a complete discussion of how discounts are applied. The following is for reference only.
-==== Discount Methods ====
+=== Discount Methods ===
   ; ''discount_quantity_amount''
   : **Accepts:** A valid [[.:coupons_and_discounts#syntax|discount]] string.
@@ Line 72: / Line 85: @@
   : **Notes:** Discounts by a percentage, based on the price of to-be-discounted products. Abbreviated ''%/$''.
-==== Discount Types ====
+=== Discount Types ===
   ; ''allunits''
   : **Also Called:** All-Units Quantity Discounts
@@ Line 105: / Line 118: @@
-==== Discount Syntax ====
+=== Discount Syntax ===
   ; Example Discount Syntax
   : ''discount_method=Discount_Name{discount_type|X-A|Y-B|Z-C}''
@@ Line 115: / Line 128: @@
-===== Subscription Product Options =====
+==== Subscription Product Options ====
   ; ''sub_frequency''
@@ Line 129: / Line 142: @@
   ; ''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:** "Today", or "immediately".
+  : **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.
@@ Line 149: / Line 162: @@
-===== Product Option Modifiers =====
+==== 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. <wrap round tip>Multiple modifiers can be chained together</wrap> with the "pipe" symbol (''|''), like ''value="S{p+1.50|w-1|c:01a|y:teeny_category}"''. When using [[advanced:hmac_validation|cart validation]] it is recommended to set your initial values high then modify //down//, rather than the other way around. See the [[advanced:hmac_validation|validation docs]] for explanation.
+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. <wrap round tip>Multiple modifiers can be chained together</wrap> with the "pipe" symbol (''|''), like ''value="S{p+1.50|w-1|c:01a|y:teeny_category}"''. When using [[advanced:hmac_validation|cart validation]] it is recommended to set your initial values high then modify //down//, rather than the other way around. See the [[advanced:hmac_validation|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
@@ Line 161: / Line 174: @@
   : **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''
+  : **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.
@@ Line 172: / Line 184: @@
 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.
+  : **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'': 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 [[.:checkout|the checkout]].
-    * ''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.
+    * ''checkout_paypal_express'': Redirects to PayPal for an [[:gateways:paypal:express_checkout|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. <wrap important>This will empty the customer's cart.</wrap>
+    * ''updateinfo'': Redirects to the checkout page with the ''updateinfo'' flag set, allowing the customer to update their billing information without actually buying anything. <wrap important>This will empty the customer's cart.</wrap> [[.:checkout#update_info_requests|More info about the ''updateinfo'' functionality.]]
   : **Default:** ''view''
   ; ''h:...'' \\ (CUSTOM Session Values)
@@ Line 205: / Line 217: @@
   ; ''fc_auth_token''
   : **Description:** Used with [[.:advanced:sso|Single Sign-On (SSO)]] to allow a customer to proceed through to the checkout.
+===== Customer Information Pre-Population =====
-==== Customer Information Pre-Population ====
+If you're considering [[.:checkout#pre-populating_the_checkout_with_customer_information|pre-populating customer info on the checkout]] you should probably look at using [[.:advanced:api|the API]] and [[.:advanced:sso|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.
-<wrap todo>TODO: Add available fields for pre-population.</wrap> Pre-population isn't a recommended method. If you need to pre-populate checkout fields it is recommended to use [[.:advanced:api|the API]] and [[.:advanced:sso|Single Sign-On (SSO)]].
+  ; ''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''
+  : **Notes:** <wrap important>Pre-populating the country is not currently supported.</wrap>
 ===== Excluding Options =====
@@ Line 237: / Line 273: @@
   ; ''^^store_name^^''
   : **Description:** See the Cart Placeholders section above.
-  ; ''^^custom_begin^^'' and ''^^custom_end^^''
+  ; ''^^custom_begin^^'' \\ ''^^custom_end^^''
   : **Description:** If you have [[.:checkout|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 [[.:multiship|multi-ship]].
 ===== Receipt Placeholders =====
 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 (note: ).
+  : **Description:** This will be replaced with the receipt contents.
   : **Notes:** <wrap important>Required.</wrap> ''^^checkout^^'' may also be used, and behaves identically to ''^^receipt^^''.
   ; ''^^cart^^''
@@ Line 285: / Line 325: @@
   : **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. It can be used in the email subject line.
+  : **Description:** This will be replaced with the transaction ID.
   ; ''^^receipt_url^^''
   : **Description:** The URL to the [[.:receipt|revisitable receipt]], for future reference.

Differences

Page Tools

Site Tools

User Tools