====== 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: <wrap hi>FoxyCart is different,</wrap> and we recommend reading more about [[.:foxycarts_reason_for_being#what_foxycart_is|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.

<wrap help>So where //do// your products live? And what //is// a product?</wrap> 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. <wrap tip>If you can build an add-to-cart link or form, FoxyCart can almost always handle the product.</wrap>

Products "live" on your site, and because you have ultimate control, you can approach products from a variety of ways.
  * Hard-coded links or forms with specific product information.
  * Links or forms populated from a database or CMS.
  * Forms with open fields for donation amounts or custom attribute fields.
  * Any combination of the above.

===== Types of Products =====
There are three "types" of products in FoxyCart:
  - "Normal" products
  - [[.:products:downloadables|Downloadable products]]
  - [[.:products:subscriptions|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.)

==== Using Links ====
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:
<code html>
<a href="https://YOURDOMAIN.foxycart.com/cart?name=A+great+product&price=5">
	Buy this Great Product!
</a>
</code>
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.
<code html>
<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>
</code>

==== 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 [[#a_complete_list_of_product_parameters|listed below]] as well as in [[.:cheat_sheet|the cheatsheet]]. If you need help, please don't hesitate to [[https://foxy.io/contact|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 =====
{{ :v:2.0:bundled_products.png?nolink&350|}}
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|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 ===
== Link example ==
<code html>
<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>
</code>

== Form Example ==
<code html>
<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>
</code>

== 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.
<code html>
<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>
</code>

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

<wrap tip>You can use the ''c'' [[.:cheat_sheet#product_option_modifiers|"code modifier"]] with bundled products.</wrap> 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 (2x4).


==== 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:

<code html>
<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>
</code>

Here's a link add-to-cart example:
<code html>
https://YOURDOMAIN.foxycart.com/cart?name=Fancy+Smartphone&price=199.99&2:name=Leather Case for Smartphone&2:price=9.99
</code>
===== 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_validation|HMAC Product Verification]], and we encourage you to [[.:hmac_validation|read more about it]]. <wrap tip>If you're using PHP, there's a helper class that will automatically sign your HTML</wrap>, 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 [[:integration:start?datasrt=&dataflt%5B%5D=system%3DWordPress|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 =====
{{section>.:cheat_sheet#product_parameters&noheader&noeditbtn&permalink&footer&nodate}}