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:
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.
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:
- The
/cart
endpoint. This is arguably the easiest approach. You'd make requests to the/cart
endpoint with theoutput=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. - 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
orbody>header
. Since Sidecart wraps everything inside a container, you'll want to change those rules, or addbody>[data-fc-store-page]>div
andbody>[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 thebody
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 thebody
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, thecart
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 (ifoutput=html
) or returns the cart (ifoutput=json
) without adding any products to the cart. Custom session values can be added on acart=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
: Withfc_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 theupdateinfo
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 theempty
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. Theh:
prefix on thename
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 thetrue
instead of thereset
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 isexample.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.
- 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) ores_MX
(Mexico, Spanish). - A value prefixed by the
h:lang
value: Whatever you pass through as thelocale
value will be prefixed with the value currently set inh:lang
, concatenated with an underscore. So if you have seth:lang=es
and pass throughlocale=MX
, the session will attempt to set the locale toes_MX
. - A value prefixed by
en_
: If the above don't match, thelocale
value will be prefixed withen_
in an attempt to match a valid locale. - 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:
html
json
(will load the JSON cart object)
- 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 totrue
orfalse
to override the setting from the shipping section of the FoxyCart admin. - Accepts:
true
orfalse
- 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.