Skip to content
Log in

Add custom data fields to your store

On this page

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. Avoid mapping formula fields: their values can change in Salesforce without the change reaching your store.

Before you add or remove a mapping

Adding a mapping starts a full re-sync of that object (some articles call this a repoll or backfill): StoreConnect requests every record of the object from Salesforce again, so existing records get the new field too. Deleting a mapping starts the same full re-sync. Changing the Access Level of an existing mapping does not.

How long a re-sync takes depends on how many records the object holds. On an object with hundreds of thousands or millions of records, such as Order, Account, or Contact, it can run for hours. While it runs, new and updated records from Salesforce take longer to reach the website, and pages on the website can slow down. See sync speed for how large syncs are paced.

These steps limit the impact of a mapping change on a large object.

  • Schedule it outside business hours. For an object with millions of records, contact StoreConnect support before you add or delete the mapping.
  • Save every mapping for the object at the same time, for example in one Data Loader insert. Mappings saved together can share one re-sync, while mappings added one at a time each start their own.
  • Get the mapping right the first time. The Object API Name and Field API Name cannot be changed after you save. To point a mapping at a different object or field, you delete it and create a new one, which starts two re-syncs.

On a standard object that already uses per-record sync opt-in, the re-sync sends only the records marked for sync.

To confirm that a re-sync has finished, contact StoreConnect support.

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 storefront 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.

The POS works differently. A mapping alone does not make a field readable in a POS template, because the POS downloads a fixed set of columns per object and adds a mapped field only when a POS Layout references it. See Custom data in POS layouts below, and Verify custom data is available in Liquid if a field renders blank.

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

```liquid

{{ 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

{{ liquid_object.data[‘geolocation_field__c’].latitude }} ```

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

```liquid

{{ 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.

```liquid

{% assign articles = articles | where: “id”, liquid_object.data[‘custom_article_id__c’] %} ```

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

```liquid

{% 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

{% 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

{% 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.

Custom data in POS layouts

To make a custom object available in POS layouts, reference it in a POS Layout. StoreConnect then includes that object in the POS sync schema and pushes records to the POS device’s local database automatically.

The same applies to a mapped custom field on a standard object such as Contact or Product. The field reaches the device only once a POS Layout Field, a POS Layout Filter, or the layout’s Sort names it. Create the layout reference, then the Custom Data Mapping, then resync. For the full procedure and how to diagnose a blank field, see Verify custom data is available in Liquid.

The layout field’s Field Name must name the same field as the mapping’s Field API Name. After creating either one, reload the POS app on the device: it only rebuilds its data schema when the app boots, so an object or column added since the last boot has nowhere to land until then. See POS layouts.

Order, Order Item, and Shipment work the same way: they are supported in POS layouts but are not part of the POS’s default data set, so each reaches the device only once a layout references it. Payment is never downloaded to the POS, so its mapped fields cannot be read in a POS template.

A Custom Data Mapping for the object must exist, but the access level does not need to be Read/Write for POS sync to work. Read-only mappings sync to POS devices just fine. Set the access level to Read/Write only if the POS needs to write field values back to Salesforce.

To query custom objects in Liquid templates (web and POS), see Liquid query.

To push changes for custom objects that are not auto-synced by StoreConnect, see Sync custom objects using flows.

Add a custom data mapping

:::warning Saving a mapping starts a full re-sync of every record of the object, and deleting the mapping later starts another. On an object with a large number of records, such as Order, plan the change outside business hours. See before you add or remove a mapping. :::

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__.

:::warning Your custom field’s API name must not match a managed StoreConnect field on the same object. For example, if an object already has s_c__Outlet_Id__c and you add your own Outlet_Id__c and map it, the sync query would select the field twice and fail. StoreConnect blocks a colliding mapping when you save it and returns an error asking you to rename the field. To resolve it, rename your custom field to a unique API name, for example Client_Outlet_Id__c, and map that instead. This only affects orgs that are not namespaced. :::

The Object API Name and Field API Name cannot be changed after a mapping is created. To point a mapping at a different object or field, delete the mapping and create a new one.

Index a field you filter on

Select Indexed on a mapping (s_c__Indexed__c on s_c__Custom_Data_Mapping__c) when you look records up by that field, so the lookup can use a database index instead of reading every record. StoreConnect builds the index automatically, normally within a few minutes of saving, and drops it when you clear the checkbox. Changing Indexed does not start a re-sync. No database change is needed from StoreConnect support.

For example, the query {%- query 'citizen_bill__c' as bills, contact_scid__c: current_customer.id -%} filters on contact_scid__c, so that mapping is a good candidate. See Surface a custom object in Liquid for the full example.

On a custom field of a standard object, such as Contact or Account, the index only helps the POS when it filters records on the server: a POS Layout Filter on that field, and the filters in remote search. {% query %} can filter on custom fields of custom objects only. Select Indexed only on fields you filter on: each index takes storage and adds a small cost every time a record is written.

Indexed builds an index in the StoreConnect database. It does not change what a POS device indexes. A device indexes the fields set up on the POS layouts; see POS storage, sync, and device administration.

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.

Related articles

Documentation Sync custom objects using flows Documentation Manage standard object sync Documentation Liquid query Documentation Liquid drops reference — global context and store Documentation Theme debugging

Was this article helpful?

Was this article helpful?