| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| v:0.7.2:cheat_sheet [2011/10/28 15:49] – external edit 127.0.0.1 | v:0.7.2:cheat_sheet [2017/06/27 18:51] (current) – [Subscription Product Options] marija |
|---|
| |
| ===== Product Parameters ===== | ===== Product Parameters ===== |
| | |
| | <wrap tip>Important Notes:</wrap> |
| | * All product parameters will be trimmed of excess leading and trailing whitespace when added to the cart. This can cause problems with [[.:hmac_validation|price validation]] if you're not careful. |
| |
| ==== Standard Product Options ==== | ==== Standard Product Options ==== |
| : **Accepts:** Any characters. | : **Accepts:** Any characters. |
| : **Example:** ''&code=ISBN 978-0-12-345678-9'' | : **Example:** ''&code=ISBN 978-0-12-345678-9'' |
| : **Notes:** <wrap round important>Required //if// using [[advanced:hmac_validation|Link and Form Validation]].</wrap> Not required otherwise. | : **Notes:** <wrap round important>Required //if// using [[.:hmac_validation|Link and Form Validation]].</wrap> Not required otherwise. |
| ; ''quantity'' | ; ''quantity'' |
| : **Description:** Quantity of products. If left blank, it will default to 1. | : **Description:** Quantity of products. If left blank, it will default to 1. |
| : **Description:** Maximum quantity that should be allowed //per product, per cart//. | : **Description:** Maximum quantity that should be allowed //per product, per cart//. |
| : **Accepts:** Integer. | : **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 //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'' | ; ''quantity_min'' |
| : **Description:** Minimum quantity that should be allowed //per product, per cart//. | : **Description:** Minimum quantity that should be allowed //per product, per cart//. |
| : **Accepts:** Integer. | : **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_min'' 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 //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'' | ; ''category'' |
| : **Description:** Category identifier for the product. | : **Description:** Category identifier for the product. |
| : **Description:** Product's per-product weight, used for shipping rate requests. | : **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. | : **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> |
| | ; ''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'' | ; ''shipto'' |
| : **Description:** Allows you to specify specific ship-to address labels for each cart add. | : **Description:** Allows you to specify specific ship-to address labels for each cart add. |
| ; CUSTOM Product Options | ; 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. | : **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. | Please see [[.:coupons_and_discounts|Coupons and Discounts]] for a complete discussion of how discounts are applied. The following is for reference only. |
| ; ''sub_startdate'' | ; ''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.). | : **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. | : **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. | * ''YYYYMMDD'' = Example: ''20070131'' = January, 31 2007. |
| : **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. | : **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'' | ; ''sub_token'' |
| : **Description:** Unique URL per subscription for loading your subscription up into a cart and modifying it's 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. | : **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). | : **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''. | : **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''. |
| |
| ==== 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 [[.:hmac_validation|cart validation]] it is recommended to set your initial values high then modify //down//, rather than the other way around. See the [[.: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'' | ; ''p'' |
| : **Modifies:** Price | : **Modifies:** Price |
| : **Setting:** ''&category=foo&size=Small{y:bar}'' would yield a ''category'' of ''bar'' | : **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. | : **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. | Transaction Options are not product-specific. Instead, they impact the entire cart or session. |
| ; ''cart'' | ; ''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:** | : **Accepts:** |
| * ''add'': The default cart action. If you don't include a cart input, ''add'' is assumed. | * ''add'': The default cart action. If you don't include a cart input, ''add'' is assumed. |
| : **Accepts:** Any valid coupon code. | : **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 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 [[.:hmac_validation|link and form validation]], do not sign the ''coupon'' value. |
| ; ''redirect'' | ; ''redirect'' |
| : **Description:** Immediately redirects the user to a page on cart load, such as ''&redirect=index.html''. | : **Description:** Immediately redirects the user to a page on cart load, such as ''&redirect=index.html''. |
| ; ''customer_country'' | ; ''customer_country'' |
| ; ''shipping_country'' | ; ''shipping_country'' |
| : **Notes:** <wrap important>Pre-populating the country is not currently supported.</wrap> | |
| |
| ===== Excluding Options ===== | ===== Excluding Options ===== |
| : **Notes:** The default receipts include an example of how these placeholders can be used. | : **Notes:** The default receipts include an example of how these placeholders can be used. |
| ; ''^^subscription_modification_begin^^''\\ ''^^subscription_modification_end^^'' | ; ''^^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). <wrap todo>Todo: Clarify this functionality and provide default text. 2011.10.28</wrap> | : **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^^'' | ; ''^^sub_token_url^^'' |
| : **Description:** Will be replaced with the ''sub_token'' URL. | : **Description:** Will be replaced with the ''sub_token'' URL. |
