The Myriad Uses of Session Variables

“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.

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

• Analytics. For example, the Google Analytics integration relies on session variables to maintain (Google, not FoxyCart) session states between your site, the cart, the checkout, and the receipt.
• Affiliate tracking systems. While most affiliate systems track primarily with cookies, there are situations where using a session variables may be more desirable.
• Storing user information. Sometimes it may be necessary to attach data to a customer that impacts later functionality. Perhaps adding a flag if they've already visited an upsell page (to prevent showing them the same page). Or adding an ID for a separate system for use with later synching.
• And much more.

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.

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.