# Add custom data fields to your store Source: https://support.storeconnect.com/articles/liquid-custom-data-fields · Last modified 21 August 2026 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 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](#custom-data-in-pos-layouts) below, and [Verify custom data is available in Liquid](verify-custom-data-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.** - Example URL: [https://yourstore.storeconnect.app/account/orders/OC1234567890123?instructions=Please+leave+at+back+door](https://yourstore.storeconnect.app/account/orders/OC1611763689953?instructions=Please+leave+at+back+door) → instructions will contain "Please leave at back door". - If the parameter is missing, it defaults to a field that is added on the orders object. - **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](verify-custom-data-in-liquid). **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](liquid-query). To push changes for custom objects that are not auto-synced by StoreConnect, see [Sync custom objects using flows](sync-custom-objects-using-flows). ## Add a custom data 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. ::: :::note 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. ::: > **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`. --- ## Follow StoreConnect - [Email Newsletter](https://getstoreconnect.com/c/lp-newsletter) - [LinkedIn Newsletter](https://www.linkedin.com/build-relation/newsletter-follow?entityUrn=7444956928444862464) - [YouTube](https://www.youtube.com/channel/UCngKdP2x8l1wcbAKW3tvU8g) - [LinkedIn](https://www.linkedin.com/company/storeconnect) - [X / Twitter](https://x.com/storeconnecthq) ## Popular Links - [Partners](https://getstoreconnect.com/partners) - [News](https://getstoreconnect.com/articles/news) - [Events](https://getstoreconnect.com/articles/events) - [Feature Comparison](https://getstoreconnect.com/how-we-compare) - [Download a free trial](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMkeKUAT) - [Book a Demo](https://getstoreconnect.com/contact) ## Documentation - [Help documentation](https://support.storeconnect.com/help-documentation) - [AI agents](https://support.storeconnect.com/ai) - [Videos & tutorials](https://support.storeconnect.com/videos-tutorials) - [Developer reference](https://support.storeconnect.com/developer-reference) - [Release notes](https://support.storeconnect.com/release-notes) - [Troubleshooting](https://support.storeconnect.com/troubleshooting) - [Trust Center](https://trust.getstoreconnect.com/) - [Status Page](https://status.storeconnect.com/) ## Contact - info@getstoreconnect.com - US +1 415 745 3230 - AUS +61 2 8365 2308 100 S Ashley Dr, Suite 600-2461 Tampa FL 33602-600 USA Level 22, Sydney Place 180 George Street Sydney, NSW, 2000, AUS --- StoreConnect Support — https://support.storeconnect.com/articles/liquid-custom-data-fields