Table of Contents

Products and FoxyCart: What They Are and What They Aren't

Where Are Your Products?

If you haven't already read “FoxyCart is different” a dozen times by now, we'll state it again: FoxyCart is different, and we recommend reading more about what FoxyCart is and isn't. Most e-commerce systems have a built in CMS, which controls not only your website, but also the way your products are displayed, and thus, your products themselves.

FoxyCart is not a CMS, and as such doesn't control your site, nor does it manage your products. The implications of this paradigm shift are far reaching, and depending on your needs it may make FoxyCart the perfect solution.

So where do your products live? And what is a product? That's a good question. Simply put, a “product” in FoxyCart is simply anything that exists in the cart (put there via a GET or POST request, if you want specifics). There are no limitations on what types of products you can create, how you create them, how many options they have, or etc. If you can build an add-to-cart link or form, FoxyCart can almost always handle the product.

Products “live” on your site, and because you have ultimate control, you can approach products from a variety of ways.

Types of Products

There are three “types” of products in FoxyCart:

  1. “Normal” products
  2. Downloadable products
  3. Subscription products

Creating a Product

To add a product to your cart, there are two methods you can use: a link or a form. If you go to the “sample code” section of your store's admin you'll find a link and a form for you to copy/paste into your own site to see how it works. (We recommend starting from that sample code if you're unfamiliar with FoxyCart.)

Links are usually the easiest option, and there are less chances for things to go wrong, but they are limited in that they cannot be changed (unless you're generating links dynamically). So whatever your add-to-cart link is for, that's it. No options, no quantity selection, no radio buttons or select boxes for product options. A simple link will look like this: 

<a href="https://YOURDOMAIN.foxycart.com/cart?name=A+great+product&price=5">
	Buy this Great Product!
</a>

If you can use a link, you probably should use a link, but if you need customers to configure their own products, read on for an example of a form.

Using Forms

Forms have many potential advantages, including the ability to use dropdowns or other input fields to set options (like size, color, etc.). To add a product using a form, you'd do something like this. 

<form action="https://YOURDOMAIN.foxycart.com/cart" method="post">
	<input type="hidden" name="name" value="A great product" />
	<input type="hidden" name="price" value="5.00" />
	<select name="size">
		<option value="small">Small</option>
		<option value="medium">Medium</option>
		<option value="large">Large</option>
	</select>
	<input type="submit" value="Buy It Now!" />
</form>

Advanced Products

You are limited only by your imagination when it comes to how you'd like your add-to-cart links or forms to function, and thus, how complex you want your products to be. There are a variety of options and parameters listed below as well as in the cheatsheet. If you need help, please don't hesitate to contact us.

Cart Limits

A Foxy cart is currently limited to a maximum of 250 products in a single transaction, and each product can have a maximum of 100 custom product options.

Product Grouping, Bundling, Ensembles

If you have a bundle of products, you can add these products in groups so that some products show up under a parent product and are not individually editable. For example, imagine selling a CD/Poster package that contains two individual products where the parent product is the CD and the child is the $0 poster. (You wouldn't want your customer to be able to delete the CD and order the poster for $0.)

You can also create items to be added to the cart together, such as accessories or an ensemble of items. This allows your customer to add all the items with one click, and they can also remove individual items or change quantities in the cart. See Adding Multiple Products without Parent/Child Relationships to view instructions for adding multiple products to the cart at once.

Adding child products

You can tell FoxyCart that a product should be attached to another product by using the product option parent_code. The parent code is simply the code of the parent to which the product should be attached.

Examples

<a href="https://YOURCARTDOMAIN.foxycart.com/cart?name=Parent+product&code=741&price=19.99&2:name=Child+product&2:price=1.99&2:parent_code=741">Add bundled products to the cart</a>
Form Example
<form action="https://YOURDOMAIN.foxycart.com/cart" method="post">
    <input type="hidden" name="name" value="Parent product" />
    <input type="hidden" name="price" value="19.99" />
    <input type="hidden" name="code" value="741" />
    <input type="hidden" name="2:name" value="Child product" />
    <input type="hidden" name="2:price" value="1.99" />
    <input type="hidden" name="2:parent_code" value="741" />
    <input type="submit" value="Buy Bundled Products" />
</form>
Form example with optional child

This example is an extension of the basic form example above, but allows for the customer to check a checkbox for whether they want to also add the child product or not. 

<form action="https://YOURDOMAIN.foxycart.com/cart" method="post">
    <input type="hidden" name="name" value="Parent product" />
    <input type="hidden" name="price" value="19.99" />
    <input type="hidden" name="code" value="741" />
    <input type="hidden" name="2:name" value="Optional Child product" />
    <input type="hidden" name="2:price" value="1.99" />
    <input type="hidden" name="2:parent_code" value="741" />
    <input type="hidden" name="2:quantity" value="0" />
    <label><input type="checkbox" name="2:quantity" value="1"> Also add the Optional Child Product ($1.99)</label>
    <br>
    <input type="submit" value="Add To Cart" />
</form>

When a parent product is deleted from the cart, the child products attached to it are deleted as well.

You can use the c "code modifier" with bundled products. On the initial add-to-cart request, the child product's parent_code value can match the original parent code (pre-modifiers) or the modified parent code. On subsequent requests, children must use the modified parent code.

Preventing child products from being removed

If you set quantity_min=1, the child product quantities will be locked to the parent product and the quantity can't be adjusted independently. You'll probably want to do this in most cases. If you set quantity_min=0 (or leave it out) the child products can be removed separate to their parent or have their quantities adjusted.

If you need to add multiple of a child product to a parent product you can set quantity_min to that amount. So for example, if you had a “Tent” parent product, and needed each tent to have 4 “Tent Peg” child products, you would add the child product with quantity_min=4. That means, that if someone orders 2 “Tent” products, the child “Tent Peg” product will have a quantity of 8 (2×4).

Subscriptions within bundled products

Only products with subscription parameters will be included as a recurring subscription, so if you bundle a non-subscription product with a subscription, the non-subscription product will not be included the next time the subscription runs and going forward.

If you bundle subscription products with different subscription parameters, they will become different subscriptions. If you bundle subscription products with the same subscription parameters, they will be on the same recurring subscription.

If a subscription is added to the cart as part of a bundle where the parent product is either not a subscription or has different subscription settings (dates), when the subscription runs the second time the parent_code will be stripped from the product so that it can be added to the transaction without error. If the parent product is a subscription and the child product is one-off, then there is no need to drop the “parent_code” on the subscription, because there isn't one.

Caution: adding multiple sets of products

You'll want to be careful about adding multiple sets of products with different child products where the quantity is locked to the parent. Let's say you have a parent bundle product with a Shirt and CD. The shirt comes in various sizes and the CD can be one of a few different varieties. If you use quantity_min=1 to lock the child products to the parent product, adding one bundle with a Large shirt and “The Carpenters” and a second bundle with a Small shirt and “The Supremes” will result in 1 bundle product with a quantity of 2 with all four sub-products attached and each with a quantity of 2. A good way to avoid this is to change something about the parent product so it's a different product each time. A random product code is a great way to do this.

Adding Multiple Products without Parent/Child Relationships

If you'd simply like to add multiple products to the cart at the same time, but not have those products be bundled or otherwise related as described above, that's totally doable. In this case, you would simply not use the parent/child relationship. In this form example, you will include all products within the same <form> tag and add the integer prefix (i.e. 1:, 2:, etc.) to each item you would like grouped. Here's a form add-to-cart example: 

<form action="https://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>

Here's a link add-to-cart example: 

https://YOURDOMAIN.foxycart.com/cart?name=Fancy+Smartphone&price=199.99&2:name=Leather Case for Smartphone&2:price=9.99

What About Security?

If you're following along, you may be asking yourself, “That's all well and good, but there's no security in that approach.” That's an excellent observation, and we have created a solution that we believe to be the most advanced and flexible approach to this problem in the world. We call it our HMAC Product Verification, and we encourage you to read more about it. If you're using PHP, there's a helper class that will automatically sign your HTML, so implementing this security enhancement may be much easier than you think.

Frequently Asked Questions about Products

Can I Import My Products?

Because FoxyCart doesn’t actually have any knowledge of your store's products, there is nothing to import into FoxyCart. If you do need to migrate from one system to another you would need to explore your options to import into whatever new CMS you’re using. For example, if you’re moving from Yahoo Stores to Wordpress, importing products is much less a question of getting the products into FoxyCart as it is getting the products into Wordpress. So long as your new system can generate links or forms, FoxyCart will function as expected.

A Complete List of Product Parameters

Important Notes:

  • All product parameters will be trimmed of excess leading and trailing whitespace when added to the cart. This can cause problems with price validation if you're not careful.
  • Case sensitivity: Product parameters are case sensitive.

Standard Product Options

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.
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. The default units for weight is lbs. This can be changes to kgs. in the category.
Notes: Supports up to a maximum of three decimal places.
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
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

Product Discounting Options

Please see Coupons and Discounts for a complete discussion of how discounts are applied. The following is for reference only.

Discount Methods

discount_quantity_amount
Accepts: A valid discount string.
Notes: Discounts by an amount, based on the quantity of to-be-discounted products. Abbreviated $/qty.
discount_quantity_percentage
Accepts: A valid discount string.
Notes: Discounts by a percentage, based on the quantity of to-be-discounted products. Abbreviated %/qty. Note that the value is based on the average of all applicable products, so applying this discount to differently priced items will result in an averaged discount.
discount_price_amount
Accepts: A valid discount string.
Notes: Discounts by an amount, based on the price of to-be-discounted products. Abbreviated $/$.
discount_price_percentage
Accepts: A valid discount string.
Notes: Discounts by a percentage, based on the price of to-be-discounted products. Abbreviated %/$. Note that the value is based on the average of all applicable products, so applying this discount to differently priced items will result in an averaged discount.

Discount Types

allunits
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. Note that “single” is the default type for coupons.
Examples:
  • Scenario: Buy two products, take $2 off of both.
    • Method: discount_quantity_amount
    • Logic: allunits|2-2

  • Scenario: Orders of five or more get a 10% on every item ordered. Orders of 10 or more get a 20% discount on every item ordered.
    • Method: discount_quantity_percentage
    • Logic: allunits|5-10|10-20
incremental
Also Called: Incremental Quantity Discounts
Description: Discounts only the units above the tiers you set.
Notes: Most useful for individual products or many products with the same price. Not useful for $/$ discount methods.
Examples:
  • Scenario: Buy two products, get additional products at $5 off. (The first two are not discounted.)
    • Method: discount_quantity_amount
    • Logic: incremental|3-5

  • Scenario: With a quantity of 1-10, all products are at 100% (no discount). With a quantity of 150, 10 products would be at 100%, 40 would be at 90%, 50 would be at 85%, and 50 would be at 80%.
    • Method: discount_quantity_percentage
    • Logic: incremental|11-10|51-15|101-20
repeat
Also Called: Buy One, Get One (BOGO), or “Repeatable Incremental Quantity Discounts”
Description: Repeatable discounts are somewhat similar to incremental discounts, but only have a single tier that repeats. Using this method you can achieve “buy one get one free” types of discounts that repeat (buy 1 get 1, or buy 3 get 3). You can also do something like “buy 3 get the 4th at $5 off”, so buying 5 or 6 would only get a single $5 discount, but buying 8 would get a $10 discount.
Notes: Not useful for $/$ discount methods. Only accepts one tier.
Examples:
  • Scenario: Buy one, get one free (100% off).
    • Method: discount_quantity_percentage
    • Logic: repeat|2-100

  • Scenario: Buy 3, get the 4th at 50% off.
    • Method: discount_quantity_percentage
    • Logic: repeat|4-50
single
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, 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.
    • Method: discount_quantity_amount
    • Logic: single|5-10

Discount Syntax

Example Discount Syntax
discount_method=Discount_Name{discount_type|X-A|Y-B|Z-C}
  • discount_method: One of the Discount Methods above.
  • Discount_Name: The text label applied to the discount and displayed to the customer in the cart. For example, “Summer Special” or “Local Coupon Discount”. A discount name is required for discounts to apply properly on cart pageloads.
  • discount_type: A Discount Type from above. Optional. Will default to single if a coupon, or allunits otherwise.
  • X, Y, Z: “Discount Tiers”. The threshold at which the Discount Amount will apply.
  • A, B, C: “Discount Amounts”. The amount or percentage discount to apply.

Subscription Product Options

sub_frequency
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 (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.
  • 1m = every month. When you use the m unit, FoxyCart will assign billing to the current (or assigned) day of the month, to be repeated every x months. The date will be moved up when necessary; if set to the 31st, it will process on the 30th of months with 30 days (or 28th/29th of February).
  • 1y = every year.
  • .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: A sub_frequency is required for a product to be treated as a subscription by FoxyCart.
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: 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. For a relative date from today, you can also specify an integer followed by a single character denoting the unit of time.
  • YYYYMMDD = Example: 20150131 = January, 31 2015.
  • DD = Example: 10 = will run on the 10th of this month or the 10th of next month if today's date is after the 10th.
  • D = Same as DD.
  • 60d = 60 days from today.
  • 2w = 2 weeks from today. For date calculations, 1w = 7d.
  • 1m = 1 month from today.
  • 1y = 1 year from today.
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 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.
sub_enddate
Description: The date a subscription should end.
Accepts: YYYYMMDD formatted date value in the future. For a relative date from today, you can also specify an integer followed by a single character denoting the unit of time.
  • YYYYMMDD = Example: 20150131 = January, 31 2015.
  • 60d = 60 days from today.
  • 2w = 2 weeks from today. For date calculations, 1w = 7d.
  • 1m = 1 month from today.
  • 1y = 1 year from today.
Notes:
  • This is an optional field. Not indicating a “sub_enddate” would make the subscription run indefinitely.
  • 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, 2015 that is supposed to run for six months and then stop, set sub_endate to 20150602 (June 2nd, 2015) so that the transaction on June 1st is not cancelled by the end date.
sub_token
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).
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.
Accepts: true to set the end date to tomorrow, or next_transaction_date to set the end date to the subscriptions next transaction date.
Notes:
  • Requires a sub_token to function. 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.
  • Prorating? 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.

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. Multiple modifiers can be chained together with the “pipe” symbol (|), like value=“S{p+1.50|w-1|c:01a|y:teeny_category}”. When using cart validation it is recommended to set your initial values high then modify down, rather than the other way around. See the 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. Modifiers cannot be applied to standard product options (ie: price or name).

p
Modifies: Price
Increasing: &size=Small{p+5}
Decreasing: &size=Small{p-5}
Setting: &size=Small{p:5}
Notes: If working with multicurrency, you may need to append the currency code to the price as required, such as {p+5CAD}. If no currency code is specified, it's assumed the price is in the store currency.
w
Modifies: Weight. Behaves like the price modifier above.
c
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
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.