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.

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 covers when you can use the update tag, and 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.

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

<textarea onblur="scAction('record:save', { object_name: 's_c__cart_item__c', s_c__sc_id__c: '{{ record.id }}', engraving_text__c: this.value })">{{ record.data.engraving_text__c }}</textarea>
```


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.