Session Objects

Use a session object to pass information to the Store Builder Library.

FastSpring sends all requests to the Store Builder Library (SBL) in the form of a session object. Then, the SBL converts the session objects into internal API directives. You can use a session object to pass order information to the store without a secure payload. This uses the push() method to pass the object to the SBL.

Each call to fastspring.builder.push() results in an updated order object response from the FastSpring backend. If you register callback functions when initializing the SBL, FastSpring will call your functions with corresponding data on each request made.

Initialize the SBL with a Session Object

Initializing the SBL sends a one-time request to FastSpring. Your website may require you to pass data to the SBL before making the request. After you initialize the SBL, your webpage can access it using public methods.

To initialize the SBL, place a session object labeled “fscSession” in the variable.

<script>
var fscSession = {
	'reset': true,
	'products' : [
					{
						'path':'example-product',
						'quantity': 1
					}
	],
	'coupon': 'YOUR10OFF'
}
</script>
<script
	id="fsc-api"
	src="https://d1f8f9xcsvx3ha.cloudfront.net/sbl/0.8.3/fastspring-builder.min.js"" type="text/javascript" 
…

Parameters

NameTypeDescription
couponstringMust contain a valid coupon. If empty, the coupon will be removed from the cart.
productsarrayEach object in the array represents a valid product. Each object must contain the Product ID and quantity.

If the product specified has a default quantity behavior set to locked or hidden, you cannot override that field. However, you can adjust the default behavior by posting to /product.
checkoutstringAccepts true or Session ID strings obtained by making a POST to the /sessions API endpoint. If you pass true, the customer is redirected to checkout. If you pass a Session ID, the SBL ignores all other fields and redirects the customer to checkout.
cleanbooleanClean the customer’s session after redirecting them to checkout. This is only valid when checkout is set to true and data-continuous is set to true when initializing the SBL.
resetbooleanTrue resets the order session.
securestringContains a secure payload for live storefronts.
tagsobjectIf you pass data through a tag, you can access it via webhook and server events.
languagestringThe 2 letter ISO language code that initiates a different checkout language.
countrystringThe 2 letter country code that initiates a different checkout country.
paymentContactobjectApplies unconfirmed customer information. Customers can see and edit these input fields.
recipientobjectThe recipient object applies unconfirmed gift recipient details to the order, and automatically selects the Gift Purchase checkbox. Customers can see and edit these input fields.
paymentMethodstringSpecifies the payment method you want to pre-select for your customer.
hideOtherPaymentMethodsbooleanHides other payment methods. Use if you want your customers to pay only using your pre-selected payment method.
invoiceDueDatestringEnter a date in yyyy-mm-dd format to override the FastSpring Default Net Terms (payment due date) setting with your own payment due date. Only yyyy-mm-dd date format will be accepted. Every other format is invalid and will default back to the FastSpring Default Net Terms setting. Your payment due date should be future dated. For more information on the FastSpring invoice due date setting, please see Store Settings.

Object Examples

Payment Contact Object

The paymentContact object applies unconfirmed customer information to the session object. Customers can see and edit these input fields.

{  
	"email":"email",
	"firstName":"firstName",
	"lastName":"lastName",
	"company":"company",
	"addressLine1":"addressLine1",
	"addressLine2":"addressLine2",
	"city":"city",
	"region":"region",
	"country":"country",
	"postalCode":"postalCode",
	"phoneNumber":"phoneNumber"
}

Recipient Object

The recipient object applies unconfirmed gift recipient details to the order, and automatically selects the Gift Purchase checkbox. Customers can see and edit these input fields.

{
	"email": "[email protected]",
	"firstName": "firstName",
	"lastName": "lastName",
	"address": {
		"addressLine1": "Address Line 1",
		"city": "City",
		"region": "California",
		"postalCode": "93101",
		"country": "US"
	},
	"memo": "Happy Birthday!"
}