Applying Customer Information to the order

Last modified October 5, 2018

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

During the checkout flow, FastSpring automatically creates a customer account based on the data entered:  email, first and last name, company name and phone number. Based on that data the unique account ID is generated for each customer which can later be used to make changes on the account, create orders on behalf of the customer (if payment information was stored on file). 

In some cases you may already have some information about the customer if you have an "account concept" (customers are logging in to access areas of your website) or customer is coming from the email broadcast and you obtained their name and email. 

In both cases information can be applied to the order to expedite checkout process. See the diagram below for all available options:

Applying Customer Information to the Order

No customer information available

In this case once checkout was completed the account will be created automatically and you can capture account information using account.created Webhook.

Some customer information is available

You can use fastspring.builder.recognize() method of the Store Builder Library to apply "tentatively known" information to the order. In this case information you applied will be pre-filled during the checkout. 

We do not recommend creating full-featured customer accounts with FastSpring with "tentatively known" information. Please use "recognize" for such information.

Complete set of customer information is available and customer is authenticated

In cases when you have confirmed set of customer information (in most cases customer confirmed their email when registering with your website or service) you can create an account with FastSpring with the data provided. In this case customers will not have to enter any personal details during checkout, only payment details will be required. 

FastSpring API Approach

Use the FastSpring API to pass customer information as follows. Note that these steps create a new FastSpring account for a customer who has never placed an order using FastSpring through your store. If you already have a FastSpring account ID on file for the customer, you can use that account ID to reference a customer during the checkout process.

  1. Create a new customer account using the /accounts endpoint to which you pass all the required information.
  2. FastSpring returns the account ID for the new customer account. You should store it for future use.
  3. Use the account to build a session and pass the account ID as well. FastSpring returns the session ID as a result.

Store Builder Library Approach

This is required when your backend is aware of customer details and the details can be passed to the checkout process.

To apply known customer information you need to use "Secure Request" – you can learn more about the feature at passing sensitive data with Secure Requests.

  "account": null, // known FS account ID. If passed the "contact" section will be ignored. 
  "accountCustomKey": null, // OR: vendor provided custom account, at least 4 characters. Valid id contains _, a-z, A-Z, 0-9, -. When passing you are required to pass "contact" object below as well
     "firstName":"Ryan", "lastName":"Dewell", 
     "company": null, //optional
     "phone": null //optional

FastSpring Account ID is available

If you already obtained and stored FastSpring account ID we recommend passing only the ID when you apply customer information to the order. This is possible with both FastSpring API (you can create session using /sessions endpoint) and Store Builder Library approach (described above). 

Important note about customer information which will be used for the order

  1. If you pass "account" (valid FastSpring account ID) in the payload the "contact" and "accountCustomKey" will be ignored. FastSpring will use information (name and email) associated with the "account". 
  2. If you pass "accountCustomKey" and there is no "account" value in the payload FastSpring will attempt to locate customer account associated with the custom key. If such account already exists (this is not the first order with the account) FastSpring will use the information associated with the "accountCustomKey" and "contact" will be ignored. 
  3. If no "account" or "accountCustomKey" are present in the payload or there is no data associated with the "accountCustomKey", FastSpring will use data from "contact" to populate the order. This data will be stored along with "accountCustomKey" if present and "account" will be generated and passed to you in webhooks. 


  • Pass only "account" if you have it. 
  • Pass only "accountCustomKey" if this is not the first order for this customer. 
  • Pass "accountCustomKey" along with a complete "contact" object if this is the first order for the customer or you are not sure. 
  • If you do not have or use accounts pass "accountCustomKey" as null. 
  • If you would like to change email for the existing account use /accounts Server API endpoint.