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

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Last revision Both sides next revision
v:2.0:cheat_sheet [2019/11/28 08:03]
adam [Cart]
v:2.0:cheat_sheet [2020/04/02 00:29]
foxybrett [Subscription Product Options]
Line 194: Line 194:
     * ''​.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.     * ''​.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>​   : **Notes:** <wrap round important>​A ''​sub_frequency''​ is required for a product to be treated as a subscription by FoxyCart.</​wrap>​
 +
   ; ''​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.).
Line 226: Line 227:
   : **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''​.
 +
   ; ''​sub_cancel''​   ; ''​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.   : **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 234:
     * <wrap round important>​Requires a ''​sub_token''​ to function.</​wrap>​ Otherwise there will not be any subscription to cancel.     * <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.     * 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.
 +
 +
 +  ; ''​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 374: Line 399:
   ; ''​context''​   ; ''​context''​
   : **Description:​** ​ Either ''​cart'',​ ''​checkout''​ or ''​receipt''​. Used for configuring various display and functionality concerns. ''​cart''​ represents both Sidecart and full page cart versions.   : **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.   : **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''​ and ''​name''​.<​code javascript>​coupons:​ { +  : **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": { 
-      "code1": { +    "code1a": { 
-          "​name":​ "Test+        "​amount":​ -1, 
-      }, +        "​id":​ "​4704984",​ 
-      "code2": [ +        "​is_applied":​ true, 
-          +        "​is_taxable":​ false, 
-              "​name":​ "Test+        ​"​name":​ "Coupon 2
-          }, +    }, 
-          +    "code2a": [ 
-              "​name":​ "Test2+        
-           ​+            "​amount":​ -1, 
-      +            "​id":​ "​4704985",​ 
-  }</​code>​+            "​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''​   ; ''​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.   : **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.

Site Tools