Collapse Menu
FastSpring App
Contact Support

Using Store Builder Library to Provide Customer Details


This article discusses how you can use the Store Builder Library to populate an order session with the customer's details, thus preventing the customer from having to enter their information on the Storefront.

FastSpring's Store Builder Library (SBL) allows you to provide customer details (such as name and email address) before initiating the checkout process. There are three ways to provide pieces of customer information using SBL:

  • Using the fastspring.builder.recognize() method
  • Using the paymentContact object within the SBL session
  • Using a secure payload 


If you need a back-end means of providing customer information—i.e., without using SBL at all--consider POSTing to the /accounts endpoint of the FastSpring API and then using /sessions to create the store session.


Using fastspring.builder.recognize() OR the paymentContact Object within the SBL Session

During checkout preparation (before launching the checkout process), you can provide customer details using the fastspring.builder.recognize() call, or within the paymentContact object of session data that you may push to SBL (e.g., using fastspring.builder.push()). Either way, the data you provide is used to pre-fill checkout fields with the information.

The fastspring.builder.recognize() call and the paymentContact object in an SBL session require at least an email address; other fields are optional. All the data provided through these methods is visible and editable during the checkout.


If you use either of these methods to supply the email address of a customer who already has an account in your FastSpring Store, any other customer details (e.g., name or address) that you do not specify by these methods may be automatically filled in from the customer account record.

The purpose of these methods is to allow you to provide "potential" customer details. For example, if a customer lands on your page from a link in an email message and your page is designed to parse the URL parameters, the email address can be "recognized" so the customer does not have to enter it again. Here is a full list of fields that can be provided through the "recognize" call or in the paymentContact object within an SBL session:

  • email
  • firstName
  • lastName
  • company
  • addressLine1
  • addressLine2
  • city
  • region
  • country
  • postalCode
  • phoneNumber

In addition to using fastspring.builder.recognize() to pass in the fields above, you can use the following methods to pass specific pieces of customer data when not using a secure payload:

fastspring.builder.language('')Pass in the two-character ISO language code (e.g., "de" for German or "fr" for French).
fastspring.builder.taxId(")For customers in locations where FastSpring accepts a tax I.D. to prevent the collection of VAT or GST.

Likewise, when using the SBL session object, the order language and the customer's tax I.D. can be supplied but must be passed outside the paymentContact object, using "language": "<2-character ISO language code>" and "taxId": "<id>", respectively.


Example 1: Three methods called separately to pass in data for a customer in Germany who wants to order in English and is exempt from paying VAT

Example: Three separate methods to pass in customer details




Example 2: Using the session object to pass in product and quantity plus data for a customer in France who wants to order in English and is exempt from paying VAT


When the product's Quantity field has a behavior of "Locked" or "Hidden", you cannot override the default quantity using the session object. Consider using a secure payload instead.
Example: Using the session object to pass in product, quantity and customer data
var s = {
  "reset": true,
  "products" : [
      "quantity": 1
  "paymentContact": {



Using a Secure Payload

Data provided inside the contact object of a secure payload is validated when submitted and is only stored if it is valid. It goes through the same validation process it would have gone through when the customer attempted to checkout, but this happens upon submission instead of waiting for the checkout. If such data passes validation, all the corresponding fields are hidden during the checkout, and only payment details will be collected. Here is a full list of fields that you can provide through the secure payload and their validation rules:

firstNameThese three fields are always required in the secure payload. For example, you cannot provide a customer's address without providing his or her name and email address. First and last names need to be at least 1 character long, and email must be a valid email address.
companyOptional, not validated

Required if enabled on the store. However, you can always provide the address, and it will be validated even if not required when creating or updating an account using a secure payload or /account call.

Fields in bold are required. Additionally, for U.S. addresses, the region must have a valid value for the supplied postalCode. For example, if the region is "US-CA," meaning California, the postalCode value must be a valid California ZIP code. If the postalCode provided does not correspond to the region, the address will not pass validation.

region format = "<2-character ISO country code>-<2-character ISO U.S. state code>", e.g., "region":"US-TX" for Texas

region (required for U.S.)


Required if enabled on the store
countryIf not provided, assumed during checkout based on geo I.P. location


Specifying the customer's country in a secure payload also sets the language automatically, overriding order language selection based on the browser's default language. You can also set the language separately in the secure payload using "language", outside the contact object.

Important:  If details in the contact object of a secure payload do not pass validation, FastSpring treats those details in the same way as a fastspring.builder.recognize() call; i.e., the data will be pre-filled, but fields will be visible during the checkout. This behavior allows customers to correct the mistakes. However, in the case of address fields, if your Storefront is not configured to display those fields, the customer does not see the fields and cannot correct the problem. Therefore, if address validation is vital to your business, we encourage you to do one of the following:

  • validate the address supplied by the customer before passing it in via a secure payload
  • ensure that your Storefront has the Force physical address collection for all orders checkbox selected (on the Checkout page of a Popup Storefront's Settings, or the General Settings page for a Web Storefront's Settings) so that the fields are displayed when necessary 


For assistance with validating the data via Store Builder Library, check out the Field Validation section of Accessing the Library from JavaScript.

In addition to the contact object of a secure payload, there are two other pieces of customer information you can pass separately in the payload:

languagePass in the two-character ISO language code (e.g., "de" for German or "fr" for French)
taxIdFor customers in locations where FastSpring accepts a tax I.D. to prevent the collection of VAT or GST


Example 1: Passing in Data for a U.S. Customer Via the Contact Object of a Secure Payload

Example:  Passing in Data for a U.S. Customer Via the Contact Object of a Secure Payload

Example 2: Passing in Language and Tax ID for an E.U. Customer Via a Secure Payload

Example 2: Passing in Language and Tax ID for an E.U. Customer Via a Secure Payload


Data Precedence

If FastSpring receives customer data from more than one source for the same session, FastSpring uses the following logic to decide which customer data applies to the order:

  • If data has been provided (and validated) through a secure payload, it is used, and no data entry (other than payment details) will be allowed.
  • If you have provided the data through the fastspring.builder.recognize() call or via the paymentContact object in an SBL session, it is used to pre-fill fields of the checkout flow. However, any data entered by the customer during the checkout overrides data supplied by these methods.
  • If data has been returned to FastSpring from a payment provider such as Amazon Pay or PayPal, it is only stored as part of the order record if it matches data entered by the customer during the checkout. Otherwise, the data entered by the customer overrides data returned from the payment method.

In simple form, the order of precedence is as follows:

  1. Secure Payload 
  2. Data entered during checkout
  3. Recognized / paymentContact data
  4. Data from the payment method