e-Commerce: cart manipulation using the 'cart' query string

When sending the user to your website, it is possible to request the website to add or remove items to the e-Commerce cart. This is done using links build as a set of commands as defined here.

The cart understands the special query string named "cart". The string is built with a set of letters and parameters. The letter 'p' stands for product and it is the activator, meaning that all the parameters prior apply to this 'p', then the parameters get reset. For this reason, you generally want the 'p' command last.

Note that the query string is interpreted whatever the page where you send the user. For this reason, you could send the user on a page which is not a product at all or simply your home page.

The following table defines each letter in alphabetical order:

Command
Letter
Syntax Description
a a!path!
a999
Add an attribute. The command expects a path to the attribute or the Short URL number (the Short URL plugin has to be enabled for the second syntax to work.)
e e Empty the cart before applying any of the other commands.
Note: the 'e' command can appear anywhere.
p p!path!
p999
The product to add. By default the quantity is assumed to be 1, although if the product is already in the cart, nothing gets changed. The quantity parameter can be changed (see q below) to change the behavior of the product command.
q q[=+-*]999[.999] Change the product quantity as defined by the quantity:
= -- force the quantity to the specified number -- WARNING: writing '=' as is in a query string parameter is not legal, you have to use %3D instead—your browser should do that automatically though.
+ -- add the quantity to the cart
- -- remove the quantity from the cart
* -- do not change the cart if the product is already in the cart (default) -- WARNING: writing a '*' as is in a URL is not legal, you have to use %2A instead—your browser should do that automatically though.
The quantity can be a decimal number with an optional fraction. The product quantity management is checked to validate the quantity (i.e. some products only allow integral numbers, multiple of certain numbers like 10, 100, 1000, etc.)
Note: The '+' is really a space since the URL encoding and decoding code sees that character as such. So you may at times see a space or %20 or %2B. All are understood the same way.

Say you create a product named "Video Game" which has URI "http://www.example.com/product/video-game". This page has a Short URL of 123.

To set the user cart to exact 1 video game and nothing else:

http://www.example.com/?cart=epproduct/video-game

Here we do not need to specify a quantity since we first cleared the cart with the 'e' command.

Now you want to make sure that the user cart has a video game, if not, add one license and since you have Short URL turned on, you can use that number:

http://www.example.com/?cart=p123

The default quantity character is '*' so if the product is already in the cart, in whatever quantity, then nothing gets modified.

It is also possible to remove one or more items from the cart, here we remove exactly one:

http://www.example.com/?cart=q-1p123

So if the user had 3 licenses in his cart, he now has 2. Note that if the user had only 1 such license, the count would drop to zero so in effect we would remove the item from the cart. However, if you want to remove an item, whatever the quantity, you should use the following syntax instead:

http://www.example.com/?cart=q%3D0p123

This says: set the quantity to zero; which is equivalent to removing the item from the cart. Note how the '=' command is written: with %3D and not directly as '='.

You may also add and/or remove multiple items all at once by specify multiple products on the command line. For example, you could add 3 of items 123, 124, and 125 as follow:

http://www.example.com/?cart=q+3p123q+3p124q+3p125

As you can see, you have to use the 'q' command each time because the 'p' command resets that number back to 1 and the operation back to '*' each time.

Snap! Websites
An Open Source CMS System in C++

Contact Us Directly