Using session objects in Store Builder

Use session objects to customize the checkout experience with JavaScript. You can preload products, apply discounts, pass customer information, or control localization before or during the buyer’s session.

There are two ways to pass session data:

Use fscSession to initialize the session before Store Builder loads
Use push() to update the session after Store Builder has loaded

Session data is stored temporarily in the browser and is not saved by FastSpring.

Why use session objects?

Customize the checkout experience using JavaScript:

Preload session data: Add products, coupons, or buyer info before checkout loads
Update cart dynamically: Use push() to change cart contents in real time
Control checkout behavior: Set payment method, localization, or tags
Prefill customer info: Add buyer or recipient details programmatically

What this guide covers

This guide explains how to:

Understand supported session object parameters
Use fscSession to initialize your store checkout with a session object
Use push() to update session fields in real-time
Pass verified customer data using a secure payload
Build session objects dynamically using URL parameters

Session object parameters

The following fields are supported when passing a session object to Store Builder.

Name	Type	Description
`products`	array	Defines the contents of the cart. Each item must include a product path and quantity. If a product has locked or hidden quantity behavior, you cannot override it. Use the `/products` API to adjust those settings.
`coupon`	string	Applies a coupon to the session. If empty, any existing coupon will be removed from the cart.
`reset`	boolean	Set to `true` to clear the cart and start a new session.
`paymentContact`	object	Prefills editable customer contact fields such as name, email, and address.
`recipient`	object	Prefills editable gift recipient fields and automatically selects the gift purchase option.
`checkout`	string	Controls whether to redirect the customer to checkout. - Pass `true` to redirect using the current session - Pass a session ID from the `/sessions` API to skip building a new session entirely
`clean`	boolean	Clears the session after redirecting to checkout. Only works when `checkout` is set to `true` and `data-continuous` is enabled during initialization.
`paymentMethod`	string	Prefills the payment method your customer should use at checkout.
`hideOtherPaymentMethods`	boolean	Hides all other payment options. Use this if you want the customer to pay using the method you pre-selected.
`invoiceDueDate`	string	Overrides the default invoice due date. Must use the `yyyy-mm-dd` format and be set to a future date. Invalid or unsupported formats will be ignored.
`language`	string	Sets the checkout language using a two-letter ISO language code (e.g., `en`, `de`, `fr`).
`country`	string	Sets the country used for checkout localization and tax calculations using a two-letter ISO country code (e.g., `US`, `CA`, `GB`).
`tags`	object	Pass custom data to your store session. Tags can be accessed in webhooks and server-side integrations.

View parameters grouped by use case

Cart configuration: products, coupon, reset
Checkout behavior: checkout, clean, paymentMethod, hideOtherPaymentMethods, invoiceDueDate
Localization: language, country
Customer details: paymentContact, recipient
Custom data: tags

Methods for passing session data

Both fscSession and push() are used to pass session data to your store checkout through Store Builder. The key difference is when and how you want to apply that data.

Method	Use case	Timing	Example
`fscSession`	Initialize your store checkout with a complete session object	Before Store Builder loads	Prefill the cart with products and customer info when the page loads
`push()`	Update specific parts of the session dynamically	After Store Builder has loaded	Update the cart or customer details in response to user actions

Initialize the session with fscSession

To initialize your store checkout with a session object, define the session as a global variable named fscSession before loading Store Builder. This lets Store Builder apply the data as soon as it loads.

Click to view example: Initialize with fscSession

JavaScript session object:

// Define the session object
var fscSession = {
  products: [
    {
      path: "your-product-path",
      quantity: 1
    }
  ],
  paymentContact: {
    email: "[email protected]"
  },
  coupon: "WELCOME10"
};

HTML markup + FastSpring script setup:

<!-- Load the Store Builder script -->
<script 
    id="fsc-api"
    src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
    type="text/javascript"
    data-storefront="your-storefront-URL">
</script>

What it does:
This setup defines a session object and loads Store Builder. When the script runs, your store checkout is automatically prefilled with the provided products, customer email, and coupon code.

What to update:

Replace your-product-path with a valid product path from your store
Replace [email protected] with the shopper’s email (optional)
Replace WELCOME10 with a valid coupon code (optional)
Replace your-storefront-URL with the full path to a checkout in your store (e.g., yourstore.test.onfastspring.com/popup-checkout)

Update the session dynamically with push()

To modify the session after Store Builder has loaded, use the push() method. This allows you to update specific parts of the session object based on customer interaction or changes in your application.

Click to view example: Update session with push()

JavaScript push() method:

fastSpring.builder.push({
  paymentContact: {
    email: "[email protected]"
  },
  coupon: "NEW10"
});

What it does:
This example updates the session by changing the customer's email and applying a new coupon. It does not affect other session fields like products or localization.

What to update:

Replace [email protected] with the shopper’s email address
Replace NEW10 with a valid coupon code
Add or remove other session object fields (such as products, tags, or recipient) based on your needs

Detailed session object examples

The following examples show common ways to use session objects in real-world setups.

Prefill customer details and language

You can prefill customer contact fields like name, email, and country using the paymentContact object in a session. If you want to override the auto-detected language (based on country), you’ll need to set it separately using fastspring.builder.language().

Click to view example: Prefill contact fields and override checkout language

JavaScript session object:

var fscSession = {
  paymentContact: {
    email: "[email protected]",
    firstName: "Jane",
    lastName: "Doe",
    country: "DE",
    language: "en"
  }
};

HTML markup + FastSpring script setup:

<script 
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does:
This setup preloads customer contact fields in the checkout form. It also sets the checkout language to English, even though the customer's country is Germany. All fields are editable by the customer at checkout.

What to update:

Replace the paymentContact fields with your customer's info
Replace your-storefront-URL with the full path to a checkout page in your store

Build a session dynamically from URL parameters

You can extract data from the query string of a page URL and apply it to a session object using JavaScript. This approach is useful for passing in product info, coupon codes, and customer contact fields when linking from emails, ads, or other storefronts.

Click to view example: Parse URL parameters into a session object

JavaScript session logic:

<script>
  var params = new URLSearchParams(document.location.search);
  var product = params.get("product");
  var email = params.get("email");
  var fname = params.get("fname");
  var lname = params.get("lname");
  var coupon = params.get("coupon");
  var fscNext = params.get("fscNext"); // used when returning from wallet providers like PayPal

  var s = {};
  fastspring.builder.reset();

  if (product) {
    s = {
      products: [
        {
          path: product,
          quantity: 1
        }
      ]
    };

    if (email) {
      s.paymentContact = { email: email };
      if (fname && lname) {
        s.paymentContact.firstName = fname;
        s.paymentContact.lastName = lname;
      }
    }

    if (coupon) {
      s.coupon = coupon;
    }

    if (fscNext) {
      console.log("Returning from a 'wallet' checkout like PayPal");
    } else {
      fastspring.builder.push(s);
      fastspring.builder.checkout();
    }
  } else {
    console.log("At least one product is required to start a checkout");
  }
</script>

What it does:
This script builds a session object using values passed in the URL. If a product is present, it adds the product, coupon, and customer info, then calls push() and checkout() — unless the customer is returning from a wallet provider.

What to update:

Adjust the parameter names or logic based on your URL structure
Replace logging or branching logic as needed for your app’s flow
Ensure the product path and coupon code are valid in your store

Example URLs:

These URLs show how to pass session data through query parameters. Each parameter is parsed and used to create a session before your store checkout loads.

Add a product to the cart

https://yourstore.com/cart.html?product=example-product

Passes: product=example-product

Add a product and apply a coupon
```
https://yourstore.com/cart.html?product=example-product&coupon=SPRING20
```
Passes: product=example-product, coupon=SPRING20

Prefill customer name and email

https://yourstore.com/cart.html?product=example-product&fname=Jane&lname=Doe&[email protected]

Passes: product=example-product, fname=Jane, lname=Doe, email=

Pass all values together

https://yourstore.com/cart.html?product=example-product&coupon=SPRING20&fname=Jane&lname=Doe&[email protected]

Passes: product, coupon, fname, lname, email

FAQs

Can I use both fscSession and push() together?

Yes. Use fscSession to set the initial session data before Store Builder loads. After the script is loaded, you can use push() to update specific fields dynamically. This is useful for adjusting session data based on user interaction or app state.

Does calling push() overwrite my entire session?

No. The push() method only updates the fields you include. Any existing session data that is not explicitly updated remains unchanged. You can safely call push() multiple times without resetting the session.

Can I build a session from URL parameters?

Yes. You can use JavaScript to extract values from the URL and apply them to a session object using push(). This is helpful when passing product, coupon, or customer information from another page, email, or campaign link.