Using Store Builder Library to Provide Customer Details

Last modified October 5, 2018

This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)

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.recgonize() method
  • Using the paymentContact object within the SBL session
  • Using a secure payload

Note

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 (prior to 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 not validated by FastSpring; it is only used to pre-fill checkout fields with the information. The information will be validated when the customer attempts to check out.

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 will be visible and editable during the checkout.

Tip

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, address) that you do not specify by these methods may be automatically filled in from the customer account record.

These methods are intended 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, the following methods can be used 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, "fr" for French, etc.).
fastspring.builder.taxId('') For customers in locations where FastSpring accepts a tax ID to prevent collection of VAT or GST.


Likewise, when using the SBL session object, the order language and the customer's tax ID 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
fastspring.builder.recognize({"email":"ne1@all.com","firstName":"Leeroy","lastName":"Jenkins","country":"DE"})

fastspring.builder.language("en")

fastspring.builder.taxId("DE1234567")


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

Example: Using the session object to pass in product, quantity and customer data
var s = {
  "reset": true,
  "products" : [
    {
      "path":"product-one",
      "quantity": 1
    }
  ],
  "paymentContact": {
    "email":"ne1@all.com",
    "firstName":"Leeroy",
    "lastName":"Jenkins",
    "country":"FR"
  },
  "language":"en",
  "taxId":"FR123456789"
}


fastspring.builder.push(s)


Using a Secure Payload

Data provided inside the contact object of a secure payload is validated when submitted, and will only be 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 will be hidden during the checkout and only payment details will be collected. Here is a full list of fields which can be provided through the secure payload and their validation rules:

firstName

These 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 name need to be at least 1 character long, and email must be a valid email address.

lastName

email

company

Optional, not validated

addressLine1

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 secure payload or /account call.

Fields in bold are required. Additionally, for U.S. addresses, region must have a valid value for the supplied postalCode. For example, if 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

addressLine2

city

region (required for US)

country

postalCode

phoneNumber

Required if enabled on the store

country

If not provided, assumed during checkout based on geo IP location

Note

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, they will be treated 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 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 will not see the fields or be able to correct the problem. Therefore, if address validation is important 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 check box 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 will be displayed when necessary

Note

FastSpring is aware that lack of data validation information in SBL responses makes it harder for you to build transparent checkout flows with great UX. We are currently working to expose validation errors and data states through the Store Builder Library.


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:

language Pass in the two-character ISO language code (e.g., "de" for German, "fr" for French, etc.)
taxId For customers in locations where FastSpring accepts a tax ID to prevent 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
{  
   "contact":{  
      "email":"ne1@all.com",
      "firstName":"Leeroy",
      "lastName":"Jenkins",
      "region":"US-CA",
      "postalCode":"93101"
   }
}


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

Example 2: Passing in Language and Tax ID for an EU Customer Via a Secure Payload
{  
   "contact":{  
      "email":"ne1@all.com",
      "firstName":"Leeroy",
      "lastName":"Jenkins",
      "country":"DE"
   },
   "language":"en",
   "taxId":"DE1234567"
}


Data Precedence

In the event that customer data is received from more than one source, FastSpring uses the following logic to decide which customer data will be used for the order:

  • If data has been provided (and validated) through a secure payload, it will be used and no data entry (other than payment details) will be allowed.
  • If data has been provided through the fastspring.builder.recognize() call or via the paymentContact object in an SBL session, it will be used to pre-fill fields of the checkout flow, but any data entered by the customer during the checkout will override data supplied by these methods.
  • If data has been returned to FastSpring from a payment provider such as Amazon Pay or PayPal, it will only be 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 will override 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