Differences

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

--- v:2.0:cheat_sheet [2018/10/05 05:50] – [Customer Information Pre-Population] adam
+++ v:2.0:cheat_sheet [2024/04/02 14:31] (current) – [Standard Product Options] adam
@@ Line 21: / Line 21: @@
   ; ''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).
+  : **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).
+  : **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.
@@ Line 61: / Line 61: @@
   : **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.
+  : **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.
   ; ''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.
+  : **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. The default units for weight is lbs. This can be changes to kgs. in the category.
   : **Notes:**  <wrap round important>Supports up to a maximum of three decimal places.</wrap>
   ; ''length'', ''width'', ''height''
@@ Line 94: / Line 94: @@
   : **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.
   : **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
@@ Line 124: / Line 125: @@
   : **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.
+  : **Notes:** ''allunits'' is the default discount type for quantity discounts applied to products. If a discount type isn't specified, ''allunits'' is applied. Note that "single" is the default type for coupons.
   : **Examples:**// //
     * **Scenario:** Buy two products, take $2 off of //both//.
@@ Line 160: / Line 161: @@
   : **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_and_discounts|coupons]], as it makes the most sense in that context. For ''%/qty'' and ''%/$'' a ''single'' discount type will yield the same discount as ''allunits''.
+  : **Notes:** ''single'' is the default discount type for [[.:coupons_and_discounts|coupons]], as it makes the most sense in that context. For ''%/qty'' and ''%/$'' a ''single'' discount type will yield the same discount as ''allunits''. Note that "allunits" is the default discount type for product and category discounts.
   : **Examples:**
     * **Scenario:** Buy any 5 products, get $10 off your order.
@@ Line 187: / Line 188: @@
   : **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,
+  : **Accepts:** An integer (maximum of 3 digits) 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''.
@@ Line 194: / Line 195: @@
     * ''.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:** <wrap round important>A ''sub_frequency'' is required for a product to be treated as a subscription by FoxyCart.</wrap>
   ; ''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.).
@@ Line 207: / Line 209: @@
   : **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.
+    * Subscription start and end dates are not currently tied to a store's timezone settings. Test your start and end dates thoroughly or [[https://foxy.io/contact|contact us]] 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.
@@ Line 226: / Line 228: @@
   : **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 indicating the subscription in question (as retrieved from the ''sub_token'') should be cancelled. By "canceling", the subscription gets a ''sub_enddate'' set, on which day it will be ended and made inactive.
@@ Line 232: / Line 235: @@
     * <wrap round important>Requires a ''sub_token'' to function.</wrap> Otherwise there will not be any subscription to cancel.
     * Foxy native email receipts will include links for the customer to be able to update or cancel their subscription. The cancel link will by default be set to ''sub_cancel=true'', so the subscription will end the following day. If you want to instead default these links to cancel on the next transaction date, you can edit the language strings for your store. On the "language" page of the Foxy administration, expand the "email" section and search for "sub_cancel=true". There will be two instances of it - simply update ''true'' to ''next_transaction_date'' to change the links.
+  ; ''sub_restart''
+  : **Description:** A flag that makes the subscription products payable "now", when used with a ''sub_token'' URL. This can (and generally //should//) be used instead of relying on past-due amounts.
+  : **Accepts:**
+    * ''true'': Collect payment "right now".
+    * ''auto'': Collect payment "right now" if and only if the subscription's past-due amount is greater than 0. Adding ''sub_restart=auto'' will eventually be the default Foxy behavior for updating subscriptions.
+  : **Notes:**
+    * This must be passed in with a ''sub_token'' or it will have no effect.
+    * Normally if you load up a ''sub_token'' URL, it will allow modifying the subscription, but will //not// change the subscription's next date, //nor will it charge the customer immediately// for the products in the cart. (A past-due amount will still be payable "now", but the rest of the products will simply bill according to the subscription's next transaction date.) This flag makes the subscription charge "now".
+    * This flag is almost always going to be preferable to customers paying the single lump sum past-due amount, as it ensure taxes, shipping, and product details are maintained.
+    * If the "reset the next transaction date on payment (past due or restart)" option on the "advanced" setting page of the Foxy administration is checked, then the next date will be updated to be one frequency ahead of todays date. If unchecked, the next date will remain as it currently is.
+  ; ''sub_modify''
+  : **Description:** Allows the "add to cart" link or form to completely replace the existing subscription loaded (in the same or a previous cart request) via the ''sub_token''. (The default behavior is to add new products to the existing subscription, and set the frequency and dates to match.)
+  : **Accepts:** ''replace''
+  : **Notes:**
+    * This is an //optional// parameter. If omitted, it will default to an "append" behavior.
+    * Upgrading/Downgrading: This can be useful in upgrading or downgrading subscriptions, or otherwise modifying subs. For instance, if you had a monthly membership service, you could create an upgrade link that replaces the currently loaded subscription (loaded via the ''sub_token'') with the upgraded subscription.
+    * Changing "Auto-Ship" Subscriptions: Similarly, you could use this functionality to replace an auto-ship order that may have multiple different products. Let's say the customer has a subscription for Product A and B, and wants to change it to Product B and 2 Product Cs, you could build an order form that includes the ''sub_modify=replace'' param, and it would replace the customer's currently loaded subscription.
+    * Removing End Dates: To //clear// an end-date from a subscription you're replacing, pass ''sub_enddate=00000000''.
+    * <wrap round note>Prorating?</wrap> At present, this //does not prorate// a subscription. So if you're halfway through a subscription period and replace the subscription, any change in the price between the old and new subscription total //will not// be prorated. We may add an additional possibilities for this parameter in the future.
@@ Line 271: / Line 298: @@
   : **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 [[.:transaction_xml_datafeed|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.
+  : **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. Maximum length for the value is 700 characters.
   ; ''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.
@@ Line 365: / Line 392: @@
 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.
+When outputting in the template, you would utilise Twig, like ''%%{{%% variablename %%}}%%''. Note that if you're looking to access data that is within arrays (such as items, or item options), then you need to access those within a ''for'' loop in the Twig, like:
+<code>
+{% for item in items %}
+  {{ item.name }}
+{% endfor %}
+</code>
+Note that the data is broken into different sections by the page scope it's available on. The cart is available on all pages (as it is present on all pages), but there are some strings that are specific to just other pages like the checkout and receipt.
 ===== Cart =====
   ; ''cart_cancel_and_continue_link''
@@ Line 374: / Line 410: @@
   ; ''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''
+  ; ''coupons''\\ ''coupons.{coupon_code}''\\ ''coupons.{coupon_code}.amount''\\ ''coupons.{coupon_code}.id''\\ ''coupons.{coupon_code}.is_applied''\\  ''coupons.{coupon_code}.is_taxable''\\ ''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.
+  : **Note:** If the cart features codes that are shared between multiple coupons (for coupons that have the "Shared Codes Allowed?" checkbox checked), these coupons will become a nested array of coupons, with the ''{coupon_code}'' still as the key. The attributes within each array item will still be the same ''amount'', ''id'', ''is_applied'', ''is_taxable'' and ''name''.<code javascript>"coupons": {
+    "code1a": {
+        "amount": -1,
+        "id": "4704984",
+        "is_applied": true,
+        "is_taxable": false,
+        "name": "Coupon 2"
+    },
+    "code2a": [
+        {
+            "amount": -1,
+            "id": "4704985",
+            "is_applied": true,
+            "is_taxable": false,
+            "name": "Coupon 1"
+        },
+        {
+            "amount": -1,
+            "id": "4704988",
+            "is_applied": true,
+            "is_taxable": false,
+            "name": "Coupon 2"
+        }
+    ]
+}</code>
   ; ''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.
@@ Line 384: / Line 445: @@
   ; ''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.
+  ; ''gift_cards''\\ ''gift_cards.{gift_card_code}''\\ ''gift_cards.{gift_card_code}.amount''\\ ''gift_cards.{gift_card_code}.id''\\ ''gift_cards.{gift_card_code}.code_id''\\ ''gift_cards.{gift_card_code}.is_applied''\\ ''gift_cards.{gift_card_code}.name''\\  ''gift_cards.{gift_card_code}.current_balance''
+  : **Description:** Gift cards associated with this cart. The ''{gift_card_code}'' is the code value used by the customer to add the gift card.
+  : **Note:** The ''current_balance'' attribute will not factor in the discount that __could__ apply from the cart or checkout. On the web receipt, ''current_balance'' will take into account the discount from that transaction, and any other uses of the gift card since then (if the receipt is being revisited). The email receipt will be the current balance of the gift card at the time the transaction was completed.
   ; ''has_eligible_coupons''
   : **Description:** If the cart contains products which can have a coupon applied to them.
@@ Line 484: / Line 548: @@
   ; ''items[].width''
   : Reserved for future use.
+  ; ''language''
+  : ** Description: ** The English name for the language of the cart as set by the template set (like ''english'', ''french'', ''german'' etc). Can be blank if using the default template set.
+  ; ''language_iso_code''
+  : ** Description: ** The 2 character ISO code for the language of the cart as set by the template set (like ''en'', ''fr'', ''de'' etc). Can be blank if using the default template set.
   ; ''loading_coupons''\\ ''loading_quantity''\\ ''loading_shipping_results''\\ ''loading_taxes''\\
   : **Description:** Used for determining if a loading animation should currently be displayed.

v2.0

Products

Business Rules

Templates

Advanced Topics

API & Backend Topics

Miscellany

Differences

Page Tools

v2.0

Products

Business Rules

Templates

Advanced Topics

API & Backend Topics

Miscellany

Differences

Page Tools

Site Tools

User Tools