Pass customer information

Passing known customer data to FastSpring streamlines the checkout experience and maintains data integrity. By pre-filling contact fields, you minimize user effort and boost conversion rates.

Furthermore, passing a unique identifier (such as an internal customer ID) ensures the new order is accurately associated with the correct record in your database, preventing duplicate accounts.

Select an approach

Your implementation strategy is determined by the specific data points you have available at the time of checkout, such as name, email, or account ID.

Scenario 1: You have no customer information

FastSpring creates an account at the end of the checkout process using the customer's email address and name. FastSpring assigns an ID to the account, and the order generates an account.created webhook.

Scenario 2: You have limited information (Name/Email)

Use the fastspring.builder.recognize command on your webpage. When the customer lands on the checkout page, the Store Builder Library (SBL) prefills their name and email address. Customers can edit these fields if necessary. When the order is complete, FastSpring assigns an ID to the account and generates an account.created webhook.

Scenario 3: You have full info, but no Account ID

If you have the customer’s name, email address, and customer ID, you can create a customer account before they complete a transaction in your store. Use the /accounts endpoint to return the account ID, or use the SBL to pass customer information on the frontend.

Scenario 4: You have an existing Account ID

Pass the customer information from the account.created webhook to the frontend with a secure payload.

We recommend passing only the account ID when you apply customer information to the order. You can do this with the /sessions API endpoint or by passing a secure request with the Store Builder Library.

Implementation methods

Use one of the methods below to pass your customer data to the checkout session.

Method 1: Store Builder Library (Secure Request)

You can pass existing information to the checkout process using a secure request. This applies authenticated customer information to the session. FastSpring requires this approach for backends that contain customer information.

Review the JSON example below to understand how to structure your payload based on the data you have.

{
  "account": "abcDEFgHiJklM1N-3OP9q",
  "accountCustomKey": "customKey",
  "contact": {  
     "email": "[email protected]",
     "firstName": "Jane",
     "lastName": "Doe",
     "company": "Company Name", 
     "phone": "555-555-5555"
   }
}

FastSpring processes the payload based on which identifiers are present:

account ID is present: FastSpring ignores the contact and accountCustomKey fields. The system uses the name and email address already associated with the provided FastSpring account ID.
accountCustomKey is present (No account ID): FastSpring attempts to locate the customer account associated with the custom key.
- Found: FastSpring automatically uses the information associated with the accountCustomKey and ignores additional info.
- Not Found: FastSpring uses data from the contact field to populate the order. After a successful transaction, FastSpring creates a new account associated with that key.
No Identifiers (account or accountCustomKey): FastSpring uses data from the contact field to populate the order. After a successful transaction, FastSpring creates a new account.

Visualize logic flow

flowchart TD
    A[Start: Process Payload] --> B{Is Account ID present?}
    B -- Yes --> C[Use Account ID]
    C --> D[Ignore 'contact' and 'customKey' fields]
    B -- No --> E{Is accountCustomKey present?}
    E -- Yes --> F{Does Key exist in FS?}
    F -- Yes --> G[Use existing account associated with Key]
    F -- No --> H[Use 'contact' data to prefill]
    H --> I[Create NEW account linked to Key after purchase]
    E -- No --> J[Use 'contact' data to prefill]
    J --> K[Create NEW standard account after purchase]

Method 2: FastSpring API

With the FastSpring API, you can create a new FastSpring account for a customer who has never completed an order in your store. If you already have an account ID on file for that customer, use it to reference them during checkout.

Create a new customer account with the /accounts endpoint. Pass all required customer information to this endpoint. The API response will include the new account ID. Store this ID for future use.

Example Response:
```
{
    "account": "abcDEFgHiJklM1N-3OP9q",
    "id": "abcDEFgHiJklM1N-3OP9q",
    "action": "account.create",
    "result": "success"
}
```

Use the account ID to build a session with the /sessions endpoint. Pass the account ID in the request body.

Example Request:

{
    "account": "abcDEFgHiJklM1N-3OP9q",
    "items": [
        {
            "product": "basic-laptop",    
            "quantity": 1
        }
    ]
}

FastSpring will return a session id which you can use to launch the checkout.

Example Response:

{
    "id": "gNFgV9ITTbyylJkiIhnmOQ",
    "currency": "USD",
    "expires": 1767372987861,
    "order": null,
    "account": "abcDEFgHiJklM1N-3OP9q",
    "subtotal": 399.99,
    "items": [
        {
        "product": "basic-laptop",
        "quantity": 1
        }
    ]
}

Append your checkout URL with /session/ and the session id.

Example Checkout URL:
```
https://yourexamplestore.onfastspring.com/session/gNFgV9ITTbyylJkiIhnmOQ
```