Mapping Custom Fields
Mapping Custom Fields in commercetools InStore.
commercetools InStore uses the following Composable Commerce resources to function:
To add attributes necessary for commercetools InStore features, you need to extend these resources using Custom Fields. Composable Commerce uses Types to define the schema for Custom Fields. You must create these Types or extend existing Types with the required Custom Fields.
If you are new to commercetools, you won't have existing Types defined. You can use a Terraform script provided by your commercetools representative to create the required Type resources.
You may need to add more Custom Fields than the defaults. However, you must not modify the commercetools InStore required fields independently in Composable Commerce. The additional fields must exist in both InStore and your Composable Commerce Project and be mapped between the two—this can be accomplished entirely in the API. Make sure that the field names match exactly, as mismatches can prevent commmercetools InStore from running.
You can identify missing mappings across all environments using the InStore Center.
Using the InStore Center to set mappings
To access the InStore Center, follow the steps to setup the initial environment as described in Using the InStore Center.
Complete the Project Settings tab of the Environment page. These settings allow the InStore Center to access Composable Commerce and pre-populate select lists on the next tab.
Go to the Custom Fields tab of the Environment page and use the following list to guide for setting the relevant Custom Fields.
List of Custom Fields for InStore
Required attributes are maintained in Composable Commerce. Custom Fields for InStore are maintained in the InStore Center.
Required attribute definitions
CUSTOMER_PAYMENTACCOUNTIDS_FIELD
Takes effect only if the Pay-On-Account feature is activated. It lists the set of account IDs that the attached Customer is eligible to charge against.
LINEITEM_FULFILLMENT_FIELD
Differentiates between in-store (take with) sales or ship-to orders.
LINEITEM_ISGIFT_FIELD
Determines the receipt printing output. It flags the Line Item as a gift to enable the Gift Receipt option.
LINEITEM_MISTID_FIELD
Supports InStore processing and retrieval of item-level sales and returns; transaction tracking and reporting; payment and discount calculation; and more. References the transaction and is the Session ID of the refund event that generated this line item.
LINEITEM_PRICEOVERRIDEAPPROVER_FIELD
Supports item-level price changes initiated within the InStore colleague app. It identifies the ID of the approver of a price override, such as a manager.
LINEITEM_PRICEOVERRIDECODE_FIELD
Supports item-level price changes initiated within the InStore colleague app. This is a code to identify the reason for a price override, such as damaged.
LINEITEM_PRICEOVERRIDETYPE_FIELD
Supports item-level price changes initiated within the InStore colleague app. It identifies the type of override, such as percent (%) or amount ($ or other).
LINEITEM_PRICEOVERRIDEVALUE_FIELD
Supports item-level price changes initiated within the InStore colleague app. This is the integer value of price override and is used with LINEITEM_PRICEOVERRIDETYPE_FIELD to resolve the override, such as $5 off or 20% off.
LINEITEM_PURCHASELINEITEM_ID_FIELD
A reference to the LineItem of the Purchase Order and is used for return Carts.
LINEITEM_PURCHASEORDERID_FIELD
Supports item-level processing and retrieval of take-with sales and delivery orders. It is the Reference to a Purchase Order.
LINEITEM_RETURNCOMMENT_FIELD
Supports item-level processing and retrieval of returns. It is the comment for a return Cart and is transferred to the ReturnLineItem after conversion to an Order. A return comment is the customer's reason for returning an item (selected in the InStore colleague app during the return workflow).
LINEITEM_SALESPERSONID_FIELD
Identifies the salesperson for the LineItem and is used for commission tracking. It supports extensibility and future functionality for item-level processing and retrieval of take-with sales and delivery orders. By default, the user who performs checkout is assigned as the salesperson.
ORDER_LOCATIONID_FIELD
Supports order-level processing and retrieval of take-with sales and delivery orders. It identifies the location (store), which in turn determines the languages, administration parameters, receipt templates, taxes, and other characteristics that are applied to the sale.
ORDER_ORDERTYPE_FIELD
Supports order-level processing and retrieval of take-with sales, delivery orders, and returns. It differentiates among purchase types, such as Normal, In-Store Purchase, In-Store Return, and In-Store Exchange.
ORDER_SEQUENCE_NUMBER_FIELD
Supports order-level processing and retrieval of take-with sales, delivery orders, and returns. It is the sequential number for the receipt and is required in some locales and upstream systems.
ORDER_USERID_FIELD
Supports order-level processing and retrieval of take-with sales, delivery orders, and returns. It specifies the ID (from the IdP) of the associate who rang up the transaction.
ORDER_WORKSTATIONID_FIELD
Supports order-level processing and retrieval of take-with sales, delivery orders, and returns. It identifies the in-store workstation (terminal), which in turn can determine the administration parameters that are applied to the transaction.
PAYMENT_ACCOUNTNAME_FIELD
Used only if the Pay-On-Account feature is activated for the retailer. It lists the payment account name associated to Cart's Customer, if any. If the Pay-On-Account feature is not in use, you can leave this blank as unpopulated fields are omitted from the Composable Commerce resource.
PAYMENT_ACCOUNTNUMBER_FIELD
Used only if the Pay-On-Account feature is activated for the retailer. It lists the payment account number associated to Cart's Customer, if any. If the Pay-On-Account feature is not in use, you can leave this blank as unpopulated fields are omitted from the Composable Commerce resource.
PAYMENT_BARCODE_FIELD
The string representation of the Wallet app barcode, which is the scannable account code.
PAYMENT_CUSTOMERNUMBER_FIELD
Supports order-level processing and retrieval and retrieval of take-with sales, delivery orders, and returns if a Customer is associated to the cart.
PAYMENT_ISSUERID_FIELD
Supports order-level processing and retrieval of take-with sales, delivery orders, and returns that involve gift card as tender. This is the InStore ID of the gift card issuer.
PAYMENT_MISTID_FIELD
Supports order-level and transaction-level processing and retrieval of take-with sales, delivery orders, and returns. This is the InStore ID of the Payment record.
ORDER_EMAILTRIGGERED_FIELD
Supports order-level processing and retrieval of take-with sales, delivery orders, and returns. This boolean indicates whether the customer requested to receive the receipt from the retailer by email, if permitted by administration parameter settings.
PAYMENT_CASHROUNDING_FIELD
Supports cash-based order-level processing and retrieval of take-with sales, delivery orders, returns, and subsequent cash reporting. Two payments of cash are generated, one of which is flagged with this Boolean indicating the cash-rounded amount.
TRANSACTION_MISTID_FIELD
The InStore ID of the payment transaction.