Add custom data fields to your store

To set this up, you'll use the Custom Data Mapping feature in the StoreConnect and Liquid templates.

You can add most any field to a storefront. However, some fields are more suitable than others.

Important information about custom data mapping

  • We do not recommend adding formula fields for data mapping, as the values of these fields can change.
  • Adding new fields to custom data mappings triggers a backfill process, which is resource-intensive. To optimize performance and minimize time:
    • Batch your custom data mapping updates by adding multiple fields simultaneously, preferably using a tool like data loader.
    • Be aware that synchronization times vary based on the size of the data set.

The custom data mappings tool

To map custom data, you need:

  • Object API name (Salesforce object)
  • Field API name (Field within the Salesforce object)
  • Access level (Read = display only; Read/Write = field data syncs back)

You can open the Custom Data Mappings page in the App Launcher.

Add custom fields to Liquid templates

Basic usage

You can access mapped data fields in any Liquid template. Note that Salesforce objects don't always naturally correspond to a liquid object. For example, Product2 corresponds to the product Liquid Object and Price Book Entries are also exposed via the product Liquid Object.

Here is an example of rendering field_1__c from The Product2 object from the context of a product page:

{{ product.data['field_1__c'] }}

Ensure your code is using the Liquid object name NOT the Salesforce object name.

Specific field types

Compound fields

Geolocation: Access latitude and longitude using CoordinateDrop.

{{ liquid_object.data['geolocation_field__c'].latitude }}

Address fields: Access components like street, city, etc., using AddressDrop.

{{ liquid_object.data['address_field__c'].street }}

ID fields: ID fields are rendered as strings. They can be used in lookups, e.g., filtering articles by an ID.

{% assign articles = articles | where: "id", liquid_object.data['custom_article_id__c'] %}

Multi-Picklist fields: Stored as arrays. Loop through options for display.

{% for option in liquid_object.data['custom_multi_picklist__c'] %}
  {{ option }}
{% endfor %}

Enable write-back to Salesforce

StoreConnect supports read/write sync functionality for custom data, allowing customers to update values on the storefront that are then pushed back into Salesforce. Note that there are special considerations if you want to write back to Person Accounts (See more below).

  1. The custom data mapping must be configured with Read/Write access.
  2. You must use the update keyword in a Liquid before or after block to trigger a write.
  3. Place the update block within the relevant template — for example, controllers/accounts/profiles/update

Example: Writing Back to a Account Object

{% liquid
  after
    update current_customer, field: "favorite_color__c", value: current_request.params.color
  endafter
%}

As this is updating a contact, this could be added inside the controllers/accounts/profiles/update template, where profile updates occur.

The code snippet above demonstrates how to write a customers favorite color back to a custom field for the current_customer. Should the customer change their mind they could come back and change the answer.

  • update current_customer: Specifies the Liquid object to update, in this case, the currently logged-in customer.
  • field: "favorite_color__c": Defines the API name of the custom field where the value will be written in Salesforce.
  • value: current_request.params.color: Assigns the value to be written to the field. Here, the value is being taken from the request parameters (e.g., form input or URL parameter).
  • The favorite_color__c for the current_customer is updated with the value passed in the request and then is synced to Salesforce.
  • This update happens after the main page or request is processed because it's inside an after block. That means the value is saved at the end, making sure everything else runs first before the update is done.

Example: Writing Back to a Order Object

{% liquid
  after
    assign instructions = current_request.params.instructions | default: ''
    assign drop_to_update = current_order

    update drop_to_update, field: 'order_special_instructions__c', value: instructions
  endafter
%}

As this is updating a customer order, this could be added inside the controllers/accounts/orders/update template, where order details occur.

The code snippet above demonstrates how to write a order special instructions back to a custom field for the current_order.

  • assign instructions = current_request.params.instructions | default: '': Captures the value of the URL parameter instructions.
  • field: "order_special_instructions__c": Defines the API name of the custom field where the value will be written in Salesforce.
  • update drop_to_update, field: 'order_special_instructions__c', value: instructions: Writes the value into the custom field order_special_instructions__c on the Order record in Salesforce.

The change is immediately synced back to Salesforce because StoreConnect’s update tag commits the change.

As a result, when a customer visits an order detail page with the ?instructions=... parameter, the custom field Order Special Instructions on that exact order is automatically updated with the provided text.

Read/write data sync to Salesforce Person Accounts

When your Salesforce org uses Person Accounts, and you need to write back to fields that conceptually belong to the Contact, you must:

  • Configure your custom data mapping on the Account object.

  • Use the related __pc fields on Account (e.g. favorite_color__pc) instead of the custom fields on Contact (e.g. favorite_color__c).

Salesforce stores Person Account contact fields on the Account record via these __pc fields, so any write-back from StoreConnect must target the __pc field on an Account to successfully update the Person Account.

When adding a new mapping, you need to populate the following fields (at minimum):

  • Object API Name: The API name of the Salesforce object. Include the namespace if the object is part of a managed package. For example, use Product2 for a standard object, custom_object__c for a custom object, or s_c__theme__c for an object from a managed package.
  • Field API Name: The API name of the field within the Salesforce object, including any namespace eg. s_c__.

Tip for Person Accounts: If you are writing back to a field on a Person Account’s Contact, use the Account object and the __pc field, e.g. current_customer + favorite_color__pc, not current_customer + favorite_color__c.

Last updated March 4, 2026