--- title: "Copy a custom field from a cart to an order" source: https://support.storeconnect.com/articles/copy-cart-custom-fields-to-orders type: article format: markdown site: StoreConnect Support — product and developer documentation for StoreConnect site_index: https://storeconnect.com/llms.txt docs_index: https://support.storeconnect.com/llms.txt note: Append .md to any page or article URL on this site to get its Markdown form. --- # Copy a custom field from a cart to an order When a customer checks out, StoreConnect creates an order from the cart. StoreConnect can copy your custom field values from the cart to the order, and from each cart item to the matching order item. For example, a gift message entered at checkout, or a job reference entered at the register, is then on the order for fulfillment, receipts, reports and Salesforce automation. Use this process to set up a field so StoreConnect copies the value. The setup is the same for the storefront and the API. The POS has one extra step. ## Which values copy A value copies when the field has the same API name on both objects and a `Read/Write` **Custom Data Mapping** on the order side. The match ignores letter case. | Cart side | Order side | |-----------|------------| | **Cart** (`s_c__Cart__c`) | **Order** (`Order`) | | **Cart Item** (`s_c__Cart_Item__c`) | **Order Item** (`OrderItem`) | On a storefront or API order, each order item also records the cart item it came from in the **Cart Item** field (`s_c__Cart_Item_Id__c`), so you can trace a copied value back to the source cart item. The field is blank on POS order items. What each channel checks: | Requirement | Storefront and API | POS | |-------------|--------------------|-----| | Same field API name on the cart side and the order side | Yes | Yes | | `Read/Write` mapping on the order or order item | Yes | Yes | | `Read/Write` mapping on the cart or cart item | Only to write the value with the `update` tag | Yes | | **POS Layout Field** naming the field on a cart or cart item layout | No | Yes | A field that fails any check stays on the cart and nothing is reported. Fields with a `Read` mapping on the order side are never copied. ## Before you start - Create the custom field on both objects in Salesforce, with the same API name and the same field type. For example, a `Gift_Message__c` text field on **Cart** and on **Order**, or an `Engraving_Text__c` text field on **Cart Item** and on **Order Item**. - Plan the mappings outside business hours. Saving a mapping on **Order** starts a full re-sync of every order. See [before you add or remove a mapping](liquid-custom-data-fields#before-you-add-or-remove-a-mapping). ## Map the field on both objects 1. Go to the **Custom Data Mappings** list. 2. Create a mapping for the cart side: - **Object API Name**: `s_c__Cart__c` (or `s_c__Cart_Item__c` for an item-level field) - **Field API Name**: `gift_message__c` - **Access Level**: `Read/Write` 3. Create a mapping for the order side with the same **Field API Name** and **Access Level**, and **Object API Name** set to `Order` (or `OrderItem` for an item-level field). The **Object API Name** and **Field API Name** cannot be changed after you save, so check the spelling before saving. ## Capture the value on the storefront The value must be on the cart before the customer completes payment, because the copy runs once, when checkout creates the order. On the storefront, write the value with the `update` tag in a Liquid controller. For example, add a `gift_message` input to the form on the customer information step of checkout, then save it to the cart in `controllers/checkout/steps/customer/update.liquid`: ```liquid {% after %} {%- liquid assign message = current_request.params.gift_message | default: "" | strip | unescape assign message = message | replace: "{", "" | replace: "}", "" if message != "" update current_cart, field: "gift_message__c", value: message endif -%} {% endafter %} ``` For an item-level field, update a line in `current_cart.items` in the same way. [Write custom data back from a template](liquid-updates) covers when you can use the `update` tag, and [theme forms](theme-forms) shows how to add an extra input to a form. Through the API, send the value in `custom_data` when you create or update the cart. Any `custom_data` you send with the checkout request is applied to the order after the copy, so it replaces a copied value with the same key. See the [StoreConnect API](storeconnect-api). ## Carry the value at the POS The POS downloads a custom field only when a **POS Layout** lists it. For a value to copy at the POS, a layout for the cart or cart item must list the field. 1. Open a **POS Layout** with **Object Name** set to `s_c__cart__c` for an order-level field, or `s_c__cart_item__c` for an item-level field. If none exists, create one. See [creating a POS layout](pos-layouts#creating-a-pos-layout). 2. In the **POS Layout Fields** related list, add a field with **Field Name** set to the lowercase API name, for example `gift_message__c`. 3. Give staff a way to enter the value. A **POS View** on the layout field can save it with the `record:save` action. For example, on a layout with **Identifier** `cart_item_record`, which adds sections to the cart item screen, this view saves an engraving as staff type it: ```html ``` See [POS views](pos-views) and the [scAction function](pos-sc-action). 4. Reload the POS app on each register, so it rebuilds the local database with the new field. See [POS storage, sync, and device administration](pos-storage-sync-and-administration). A **POS Layout** with the short **Object Name** `cart` does not count. Use the full API name. The register copies the values from the cart it holds, so the copy works offline. ## Confirm it worked Place a test order with a value in the field, on the storefront or at the POS. Open the **Order** record in Salesforce: the **Gift Message** field holds the value entered on the cart. For an item-level field, check the **Order Item** records. ## Behavior to plan for - **Storefront orders copy once.** A change to the cart after the order exists, for example while the customer retries a failed payment, does not reach the order. - **POS open orders keep copying.** StoreConnect copies the values to an open order (tab) when the tab is created and each time it is saved. The values are final at checkout. - **At the POS, only values on the register are copied.** Values staff enter on the register always copy. If a cart or cart item field is filled in by Salesforce or another process after the item is added, complete the sale only after that value has reached the register, or it may not copy to the order or order item. - **Clearing a field on the cart does not clear the order.** An empty value is not sent, so an order that already holds a value keeps it. - **The copy adds to the order's custom data.** Other custom fields already on the order are left as they are. - **Keep the field type the same on both objects.** The POS converts the value to the order-side field type. The storefront copies the stored value as it is, so a text field on the cart and a date field on the order can fail to sync to Salesforce. - **A failed copy never blocks the order.** The order is created without the field, and the error is logged for StoreConnect support. - **Cart fulfillments are not copied** to shipments. --- ## Follow StoreConnect - [Email Newsletter](https://storeconnect.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://storeconnect.com/partners) - [Become a Partner](https://storeconnect.com/become-a-partner) - [News](https://storeconnect.com/articles/news) - [Events](https://storeconnect.com/articles/events) - [Feature Comparison](https://storeconnect.com/how-we-compare) - [Download a free trial](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMkeKUAT) - [Book a Demo](https://storeconnect.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 ## Machine-readable - [Site index for agents](https://storeconnect.com/llms.txt): curated map of the StoreConnect site in llms.txt format - [Documentation index for agents](https://support.storeconnect.com/llms.txt): full technical and product documentation map Every page and article on this site has a Markdown rendering: append `.md` to its URL. Continue in Markdown: [Help documentation](https://support.storeconnect.com/help-documentation.md) · [Developer reference](https://support.storeconnect.com/developer-reference.md) · [Videos & tutorials](https://support.storeconnect.com/videos-tutorials.md) · [Release notes](https://support.storeconnect.com/release-notes.md) --- StoreConnect Support — https://support.storeconnect.com/articles/copy-cart-custom-fields-to-orders