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

Table of Contents

The Cart of The Foxy

What Is The Cart?

The “cart” in “FoxyCart” is where your products are stored for each visitor to your website. The cart itself is highly flexible, and can be loaded as HTML or as JSON, allowing for unlimited customization potential.

When we say “the cart” we will generally be referring to the cart when it is loaded by itself, but a representation of the cart is also usually included on the checkout, the receipt, and email receipts. When the cart is included in those sections it is mostly static, displaying its current contents. When you're interacting with it directly is where you'll see it in action.

The Standard Responsive Cart Implementation

The default approach to the FoxyCart cart is two-fold. The first example is what we call the Sidecart approach. It looks like this: The FoxyCart Sidecart

It lives on your own site and provide a quick and easy way for your customers to add product to (and interact with) the cart.

The second option is the “full-page cart”, which is used for older browsers (IE8 and IE9), and can be used instead of the Sidecart if desired. The FoxyCart cart

There are a few things to notice here:

  • Products, including all product options, quantities, and prices. Product thumbnails, if configured, are also displayed.
  • Quantity fields allow for modifying the quantity of products in the cart.
  • Remove links to remove the product from the cart.
  • A link to checkout using PayPal Express Checkout, if configured for the store.
  • A link to checkout normally, if a gateway is configured for the store.
  • A link to continue shopping.
  • A link to add a coupon code, if active coupon codes exist for the store. (Otherwise this link will not be shown, as studies have shown that they can decrease conversion rates. Potential customers may leave your site to search for a coupon code, where they may become distracted or find a competitor.)
  • Postal code input if the store and cart requires shipping
  • A subtotal and order total.
  • Multi-ship information
  • Future subscription information.

It's important to note that though this is what the FoxyCart-powered cart will look like by default, but you can customize nearly every aspect to fit your specific needs.

A Note about jQuery

FoxyCart is dependent on jQuery. It's been tested with versions 1.10 and up. The FoxyCart loader will determine if you have jQuery available on your page and if not, load it, but this loading will take place AFTER the document.ready javascript event. This is the event most jQuery plugins listen for, so if you have jQuery plugins on your page it is imperative you include your own copy of jQuery otherwise those plugins will throw a jQuery is not defined error on pageload which will make you not happy. To reiterate: You should only use the FoxyCart jQuery if you have no other dependences on jQuery in your code.

Serverside Cart Interactions

In addition to (or instead of) interacting with the cart via links and forms that initiate in the visitor's browser, you can also create and modify carts via serverside methods. This approach is far more specific and uncommon, but can make sense in more customized used cases. There are two different methods to interact with the cart in this way:

  1. The /cart endpoint. This is arguably the easiest approach. You'd make requests to the /cart endpoint with the output=json option (so you can easily parse the responses), using all the normal /cart parameters that you'd use in a normal link or form.
  2. The Hypermedia API. This is more difficult, but this hAPI offers far more flexibility and functionality in other aspects of your integration, and using a consistent approach may be desirable if you're already building agains the hypermedia API.

The most common use case for this approach is if you've already got cart functionality within your system, and just want to rely on Foxy as the hosted checkout/payment page. For more details on this approach, please see Using Foxy Without the Cart.

Customizing Your Cart

Customizing the HTML version of your cart (as opposed to a JSON-based approach) is basically identical to customizing any other FoxyCart template, except for the Sidecart, which by default loads a bit differently because it's included in your own site. The issue is that the sidecart display can potentially be impacted by CSS on your site that might bleed into the sidecart styling. (This can be beneficial if that's your intent, but we've taken steps to ensure it doesn't happen inadvertently.)

Customizing the Sidecart

All the Sidecart styling is namespaced in a #fc ID, so if you'd like to use CSS to override any aspect of the sidecart, you'll need to ensure your CSS rules can override the defaults. There is a great deal of information about the HTML and CSS used to build all templates on the Templates documentation page.

Common Problems with Sidecart

  • Jumping elements: The most common problem with implementing Sidecart is with statically positioned elements jumping when sidecart slides in. This is often caused by top or bottom margin or padding on the body element itself. If you can move the top/bottom margin/padding to a different element, this jumping behavior will likely be resolved.
  • Missing styles: If your page radically changes its styling when Sidecart slides in, check to see if you've got any direct descendent rules off the body, like body>div or body>header. Since Sidecart wraps everything inside a container, you'll want to change those rules, or add body>[data-fc-store-page]>div and body>[data-fc-store-page]>header as well. (The [data-fc-store-page] is the data attribute on the wrapping element.)
  • Jumping background: We've fixed this, but if you're seeing just the background image jumping, please let us know on our forum.

Interacting With the Cart

Adding Products to the Cart

Adding products to your cart is discussed in the products documentation.

Note: A Foxy cart is currently limited to 250 products in a single cart session.

Viewing the Cart

If you'd just like to load the cart without adding a product to it (ie. a “View Cart” button), you'd link to the cart like you were adding a product, but just include the cart=view option (as in /cart?cart=view) instead of any product options. This is discussed below in non-product cart parameters.

The Persistent "Mini-Cart"

Though you can get more advanced with the JSON cart interaction, FoxyCart's default javascript provides easy helper functions to create a persistent "mini-cart".

Bypassing Your SideCart

There are a few methods to to skip the sidecart and go to the full-page cart instead:

  • Change the “Customize your cart type” setting in the templates → configuration section of your admin. This is the easiest method, but is all or nothing, so if you want conditional sidecart bypassing, read on.
  • Add fc-sidecart--bypass as a class to the cart link or form to disable sidecart on that particular link or form. Add the class to the body element to disable sidecart for the entire page.
  • Add data-fc-sidecart-bypass as an attribute to the link or form to disable sidecart on that particular link or form. Add the attribute to the body element to disable sidecart for the entire page.

It doesn't matter which approach you use. We offer both methods purely for convenience.

Bypassing Your Cart Entirely (Straight to Checkout)

There are a handful of reasons that you might want bypass the cart entirely and proceed either directly to your checkout, or somewhere else. For example, if you're selling just a single product, or a single conference registration, you might want to both empty the cart on a new product being added to the cart and then proceed directly to checkout. Or you may want to add the product to the cart but then redirect to an upsell page. A variety of options are available in this regard. Check the cart parameters section below for details.

Advanced (JSONP) Cart Implementations

If you've yawned at all of the above details about customization, if you need a highly specific cart display, or if you need to interact with the cart programmatically like via server-side programming or Flash, then the cart's JSON and JSONP functionality will be of interest. More details are here.

Non-Product Cart Parameters

Transaction Options are parameters included within cart requests that are not product-specific. Instead, they impact the entire cart or session. In the same way as the Product Options above, Transaction Options are included within the cart request, either as an additional parameter in the add to cart link, or as an input within a form.

cart
Description: The cart parameter allows for various behaviors to be performed when the cart is requested. Note, the cart parameter is separate from the /cart portion of the cart URL. Within an add to cart link it should be separate like /cart?cart=view, or specified as a hidden input in an add to cart form.
Accepts:
  • add: The default cart action. If you don't include a cart input, add is assumed.
  • view: Displays the cart (if output=html) or returns the cart (if output=json) without adding any products to the cart. Custom session values can be added on a cart=view request.
  • checkout: Redirects to the checkout page immediately. Any “add to cart” requests are processed first, so you can add a product to the cart and go immediately to the checkout.
  • checkout: With fc_payment_method=paypal_ec Redirects to PayPal Express Checkout with reference transactions immediately. Any “add to cart” requests are processed first, so you can add a product to the cart and go immediately to the checkout.
  • checkout_paypal_express: Redirects to PayPal for the legacy Express Checkout immediately. Any “add to cart” requests are processed first, so you can add a product to the cart and go immediately to the checkout.
  • updateinfo: Redirects to the checkout page with the updateinfo flag set, allowing the customer to update their billing information without actually buying anything. This will empty the customer's cart. More info about the ''updateinfo'' functionality.
  • empty: Deprecated. Will be removed in a future release. Use the empty parameter instead.
Default: view
h:…
(CUSTOM Session Values)
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 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. 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.
Accepts:
  • true: Empties the cart, including all custom session values, coupons, customer address and prepopulation values, shipping selections, etc.
  • reset: Does all of the above but also resets the cookie. The use case for this is uncommon, so in general you should use the true instead of the reset value.
coupon
Description: Adds one or more coupon codes directly to the cart.
Accepts: Any valid coupon codes, separated by a comma.
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 link and form validation, do not sign the coupon value.
redirect
Description: Immediately redirects the user to a page on cart load, such as &redirect=index.html.
Accepts: path/to/file.ext
Notes: For security reasons, the path must be at the store's domain (as entered in the store's FoxyCart settings). ie. You cannot redirect to example.org/path/to/file.ext if your store's domain in FoxyCart is example.com. Additionally, you may need to URL encode any ? and & symbols in a redirection path.
locale
Experimental Functionality: This feature will be further tested and documented. Please refer to FoxyCart's multicurrency documentation for more info.
Description: Sets the currency for the cart. Converts any existing items in the cart from the current currency (the store's default) to the newly specified currency.
Accepts: FoxyCart will attempt to match a locale in the following order. If no locale is matched, it will continue to the next option and attempt a match there.
  1. A full locale code in the format of 2 character language code, followed by an underscore and a two character territory, such as en_US (US, English) or es_MX (Mexico, Spanish).
  2. A value prefixed by the h:lang value: Whatever you pass through as the locale value will be prefixed with the value currently set in h:lang, concatenated with an underscore. So if you have set h:lang=es and pass through locale=MX, the session will attempt to set the locale to es_MX.
  3. A value prefixed by en_: If the above don't match, the locale value will be prefixed with en_ in an attempt to match a valid locale.
  4. Case-insensitive locale match
Notes: Changing the locale will empty the cart of its products. Products added in the same request will work fine, however.
template_set
Description: Used to specify a specific template set to apply to this cart session
Accepts: Any valid template set code
Notes: If a template set is applied which changes the locale of the cart session, any existing products will be removed from the cart. Products added in the same request will be added normally.
output
Description: Specify the output format for the cart request.
Accepts:
Default: html
callback
Description: Used to make an output=json request return a JSONP (instead of JSON) response. This will typically be used with a javascript library like jQuery.
fc_auth_token
Description: Used with Single Sign-On (SSO) to allow a customer to proceed through to the checkout.
h:shipto_residential
Description: Since shipping rates can be returned from the cart (where the company address field isn't entered), and since the difference between residential and commercial shipping rates can be important, you can set this to true or false to override the setting from the shipping section of the FoxyCart admin.
Accepts: true or false
Default: n/a. Shipping rates are determined in the shipping settings in the FoxyCart admin.
h:bypass_maintenance_mode
Description: You can set this to true to override the maintenance mode for your store (and view the checkout normally).
Accepts: true
Default: false
utm_source, utm_medium, utm_campaign, utm_term, utm_content, _ke
Description: URL parameters for Google Analytics custom campaigns and Klayvio. When specified as part of an add to cart, they'll be included in the next page load of either the cart or the checkout.
Notes: These values should not be encrypted when using link/form encryption, and they must be passed as URL parameters - passing them within the hash is not supported. The values are not stored in the session at all - they're just used on the resulting page load of the add to cart action.

Page Tools

Site Tools