Documentation

Map Custom Fields

Map Custom Fields required by commercetools InStore.

InStore features rely on specific Composable Commerce resources and Custom Fields that you must provision. By using these Custom Fields, InStore is able to access certain Composable Commerce resources that enable functionalities in the InStore colleague app, or your own in-store colleague app. For example, the LINEITEM_FULFILLMENT_FIELD allows InStore to track whether a sale made in-store is a take with sale or a ship to sale, and this is linked to the Order that is maintained by Composable Commerce. By mapping and using these Custom Fields, InStore can associate transaction, payment, and item-level context with the underlying Composable Commerce resources. This enables functionality in the InStore colleague app, or your own in-store application, such as reporting, fulfillment workflows, returns processing, and price overrides. For example, the LINEITEM_FULFILLMENT_FIELD differentiates between in-store (take-with) sales and ship-to orders, and the value is persisted with the related Order in Composable Commerce.

Composable Commerce resources used by InStore

InStore uses the following Composable Commerce resources:

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. Create new Types or extend existing Types to include the required 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 additional Custom Fields beyond the required set. Do not modify the InStore required fields independently in Composable Commerce. Any extra fields must exist in both InStore and the Composable Commerce Project and be mapped: this can be done entirely through the API or using the InStore Center.

Field names must match exactly. A mismatch blocks InStore from operating for affected resources.

Use the InStore Center to identify missing mappings across all environments.

Set mappings in the InStore Center

  1. Access the InStore Center after you complete the initial environment setup described in Using the InStore Center.
  2. Complete the Project Settings tab on the Environment page. These settings allow the InStore Center to access Composable Commerce and pre-populate select lists on the next tab.
  3. Go to the Custom Fields tab on the Environment page and use the list below to add or verify the required fields.

Custom Fields reference

Required attributes are maintained in Composable Commerce. InStore-specific Custom Fields are maintained in the InStore Center.

Type KeyRequired AttributeCustom Field
CustomerCUSTOMER_PAYMENTACCOUNTIDS_FIELD\paymentAccountIds
LineItemLINEITEM_FULFILLMENT_FIELD\fulfillment
LineItemLINEITEM_ISGIFT_FIELD\isGift
LineItemLINEITEM_MISTID_FIELD\mistId
LineItemLINEITEM_PRICEOVERRIDEAPPROVER_FIELD\priceOverrideApprover
LineItemLINEITEM_PRICEOVERRIDECODE_FIELD\priceOverrideCode
LineItemLINEITEM_PRICEOVERRIDETYPE_FIELD\priceOverrideType
LineItemLINEITEM_PRICEOVERRIDEVALUE_FIELD\priceOverrideValue
LineItemLINEITEM_PURCHASELINEITEM_ID_FIELD\purchaseLineItemId
LineItemLINEITEM_PURCHASEORDERID_FIELD\purchaseOrderId
LineItemLINEITEM_RETURNCOMMENT_FIELD\returnComment
LineItemLINEITEM_SALESPERSONID_FIELD\salespersonId
Cart/OrderORDER_LOCATIONID_FIELD\locationId
Cart/OrderORDER_ORDERTYPE_FIELD\orderType
Cart/OrderORDER_SEQUENCE_NUMBER_FIELD\sequenceNumber
Cart/OrderORDER_USERID_FIELD\userId
Cart/OrderORDER_WORKSTATIONID_FIELD\workstationId
PaymentPAYMENT_ACCOUNTNAME_FIELD\accountName
PaymentPAYMENT_ACCOUNTNUMBER_FIELD\accountNumber
PaymentPAYMENT_BARCODE_FIELD\barcode
PaymentPAYMENT_CUSTOMERNUMBER_FIELD\customerNumber
PaymentPAYMENT_ISSUERID_FIELD\issuerId
PaymentPAYMENT_MISTID_FIELD\mistId
TransactionORDER_EMAILTRIGGERED_FIELD\isEmailTriggered
TransactionPAYMENT_CASHROUNDING_FIELD\cashRounding
TransactionTRANSACTION_MISTID_FIELD\mistId

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 and ship-to orders.

LINEITEM_ISGIFT_FIELD

Flags the Line Item as a gift to enable the Gift Receipt option and change receipt printing output in the InStore colleague app.

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 the override. Used with LINEITEM_PRICEOVERRIDETYPE_FIELD to resolve the override (for example, $5 off or 20% off).

LINEITEM_PURCHASELINEITEM_ID_FIELD

A reference to the LineItem of the purchase order. Used for return Carts.

LINEITEM_PURCHASEORDERID_FIELD

Supports item-level processing and retrieval of take-with sales and delivery orders. It is a reference to a purchase order (PO) number. For more information about purchase order numbers, see the Prompt_for_Purchase_Order_POA administration parameter.

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. This field is the sequential number for the receipt and is required in some locales and upstream systems. For more information about this field, see Sample InStore order numbers.

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

Order number structure

Order numbers in InStore have the following components:

  • Cart Key Prefix: Optional. Set in the InStore Center > Environment > Project Settings. The prefix must be unique across your tenant environments and can be used only once per Composable Commerce Project.
  • Location ID: Optional. Alphanumeric (typically 3–6 characters). Defined in the InStore Center > Locations > Add Location.
  • Workstation ID: Optional. Alphanumeric (up to 3 characters). Defined in the InStore colleague app > Manage Devices > Workstations.
  • Sequence Number Length: Optional. The first Cart or transaction uses 1. Subsequent numbers increment sequentially as Cart IDs are created. Length is 3–9 digits (6 is common) and is set in the InStore Center. Left-pad with zeros to the configured length.
In the following example, 806 is the prefix, 001 is the location ID, 01 is the workstation ID, and 14 (rendered as 000014 for a length of 6) is the sequence number:
80600101000014
In the following example, the order number is shorter because the prefix is one digit (3):
300101001131