Customer data

Customer data can get retrieved and set through methods called to the CF.customer object with data column keys. This will make the necessary requests to our backend API services to set the data. Only keys defined as data columns will be available.

Read data

To get data from the customer, call CF.customer.get("column_key", "column_key", ...). If you pass it a single column key, only the value of that column will be returned. Otherwise, an object containing multiple key/value pairs will be returned.

// Get a single column's data
var firstName = CF.customer.get("first_name");
//    -> "John"

// Get multiple columns' data
var data = CF.customer.get("first_name", "last_name");
//    -> { first_name: "John", last_name: "Smith" }

// Another way to accomplish getting multiple columns' data
data = CF.customer.get(["first_name", "last_name"]);
//    -> { first_name: "John", last_name: "Smith" }

Note

This function will not return changes made by forms in realtime. If you’d like to read values directly from form fields, see our Form API docs.

Write data

Provide a data column key and value to apply with customer.set. Note these changes are “staged” for saving and not immediately pushed to the customer’s record.

// Set a single column's value, number type
CF.customer.set("some_column", 123);

// Date type
CF.customer.set("event_day", "2015-04-13");

// Datetime type
CF.customer.set("last_seen_at", "2019-12-24T05:32:06+11:00");

// Phone type
CF.customer.set("phone", "+112345677890");

// File type
CF.customer.set("file", {
  extension: "png",
  name: "color-light@4x.png",
  size: 58091,
  type: "image/png",
  url: "https://example.com/assets/color-light@4x.png"
});

// List type
// Note: this does not accept objects as array elements (see group_list instead)
CF.customer.set("favorite_colors", ["red", "green", "blue"]);

// Group type
CF.customer.set("preferences", {
  "show_avatar": true,
  "homepage_url": "https://cantnotbuythis.com",
  "nickname": "Pete"
});

// Group list type
CF.customer.set("athletes", [
  {
    "name": "Jim",
    "left_handed": false,
    "position": "forward"
  },
  {
    "name": "Joe",
    "left_handed": true,
    "position": "defender"
  },
  {
    "name": "Jake",
    "left_handed": false,
    "position": "mid"
  }
]);

Note

This function will not cause any form’s fields to change. If you’d like to programatically apply field changes, see our Form API docs.

You can also pass an object to CF.customer.set to merge multiple changes into the existing data in a single call. This will also merge it into CF.customer.unsavedChanges.

// Set multiple columns' values
CF.customer.set({
  some_column: 123,
  another_column: "woohoo!",
});

Save the customer

Call CF.customer.save to submit customer data to our servers. The parameter of options is not required, however if you’d like to perform actions such as auto-login or redirecting, it is necessary. See this example:

// Each property here is optional!
var customerSaveOptions = {
  // If a customer account is created, determine whether or not to auto-login.
  login: true,

  // After the customer is successfully saved and/or automatically logged in, determine whether or not to redirect.
  redirect: true,

  /* 
    Relative path on the storefront to redirect to after saving the customer.
    For example: `/account`, `/pages/some-page`, `/collections`, ...
  */
  redirectUrl: "/account",

  /* 
    Tells our servers which form was submitted. Allows us to track form submissions and populate
    event details with form data. Obtain the form ID from the url when viewing the form builder:
      https://customr.heliumdev.com/forms/<form ID>
  */
  formId: "a34Kl0",

  /*
    Sends a payload including only this data
  */
  data: {
    specific: 'data'
  }
};

CF.customer
  .save(customerSaveOptions) // Providing an options object in the first place is optional.
  .then(function(errorObj) {
    if (errorObj) {
      /* 
        errorObj is an object containing data column key to string array pairs. 
        Here's an example of what it might look like:

        {
          "phone": ["is invalid"],
          "email": ["has already been taken"],
        }
      */
    } else {
      // You're all set! Any unsaved changes that have been made 
      // to the customer's data have now been saved.
    }
  })
  .catch(function(err) {
    // Something wrong happened :(

    console.error("Could not save customer", err);
  });

Error handling

On occasion, people don’t write perfect software (including us.) It’s crucial to handle errors if our servers respond with them. We strongly suggest you look into it.

Save specific keys of data

By default, the save function saves all unsaved changes. You can change this behavior to only submit certain data. There are two ways to accomplish this, the first is to supply CF.customer.save with an object containing the dataset you’d like to submit:

CF.customer.set({ first_name: "John", last_name: "Smith" });

CF.customer.save({
  data: CF.customer.get('first_name', 'last_name')
}).then(function() {
  // only first_name and last_name were saved
})

The second is to use the short-hand CF.customer.update function:

CF.customer
  .update({
    first_name: "John",
    last_name: "Smith"
  })
  .then(function() {
    // Only first_name and last_name were saved!
  });

Next up: Customer tags