Table of Contents

The Myriad Uses of Session Variables

What Session Variables Are

“Session Variables” allow you to store information (as name/value pairs) in a user's cart, independently of any products in the cart. Unlike a product, which is visible in the cart and added by the customer, session variables aren't necessarily visible to the visitor, nor would the visitor know that a session variable has been set. You can think of session variables as a way to attach extra information to the session (fancy that) for you to use later.

Potential Uses of Session Variables

Though you could use session variables for any number of integration or data tracking purposes, the most common uses are:

How to Set Session Variables

Setting a session variable is as easy as adding an h: prefix to any value being passed to the cart. Here's a quick example of adding a product with a color value equal to blue, and a session variable named referrer set to charlie.

<!-- First, a link -->
<a href="https://YOURDOMAIN.foxycart.com/cart?name=A great product&price=5&color=blue&h:referrer=charlie">
	Buy this Great Product!
</a>
 
<!-- Next, a form -->
<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" />
	<input type="hidden" name="color" value="blue" />
	<input type="hidden" name="h:referrer" value="charlie" />
	<input type="submit" value="Buy It Now!" />
</form>

Either of those would add the product to the cart, but would also add the referrer value to the session, so your JSON would look something like this:

{
	"products":[
		{
			"id": "5476698",
			"name": "A great product",
			"code": "",
			"image": "",
			"url": "",
			"length": "0",
			"width": "0",
			"height": "0",
			"options": {"color":"blue"},
			"quantity": 1,
			"price_each": 5,
			"price": 5,
			"weight_each": 1,
			"weight": 1,
			"shipto": "",
			"category": "DEFAULT",
			"sub_frequency": "",
			"sub_startdate": "0000-00-00",
			"sub_nextdate": "0000-00-00",
			"sub_enddate": "0000-00-00"
		}
	],
	"product_count": 1,
	"total_item_price": 5,
	"total_discount": 0,
	"total_price": 5,
	"total_weight": 1,
	"session_id": "56b5kmov0lthokufk1uhv0hca2",
	"custom_fields":{
		"referrer":"charlie"
	},
	"messages":{
		"errors":[],
		"warnings":[],
		"info":[]
	}
}

Notice that the custom_fields is at the top level of the JSON, not associated with specific products being added to the cart.

How to Access Session Variables

Given the intended usage of session variables, it shouldn't be surprising that these values are not displayed to the user at any point, but they are accessible via the JSON cart object during the user's visit, and via the transaction XML datafeed or the API after the transaction is completed.