# Map Custom Fields

Map Custom Fields required by commercetools InStore.

InStore features rely on specific resources and Custom Fields that you must provision.
By using these Custom Fields, InStore is able to access certain resources that enable functionalities in the InStore POS, or your own in-store application. 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.
By mapping and using these Custom Fields, InStore can associate transaction, payment, and item-level context with the underlying resources. This enables functionality in the InStore POS, or your own in-store application, such as reporting, fulfillment workflows, returns processing, and price overrides. For example, the [`LINEITEM_FULFILLMENT_FIELD`](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_fulfillment_field) differentiates between in-store (take-with) sales and ship-to orders, and the value is persisted with the related Order.

## Resources used by InStore

InStore uses the following resources:

- [Carts](/api/projects/carts.md#cart)
- [Orders](/api/projects/orders.md#order)
- [Line Items](/api/projects/carts.md#lineitem)
- [Payments](/api/projects/payments.md#payment)
- [Transactions](/api/projects/payments.md#transaction)
- [Customers](/api/projects/customers.md#customer)

To add attributes necessary for commercetools InStore features, you need to extend these resources using Custom Fields. [Types](/api/projects/types.md) 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 your Project. Any extra fields must exist in both InStore and your 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](/instore/use-the-instore-center/overview.md).

2. Complete the **Project Settings** tab on the **Environment** [page](/instore/use-the-instore-center/environment.md#project-settings-tab). These settings allow the InStore Center to access your Project and pre-populate select lists on the next tab.

3. Go to the **Custom Fields** tab on the **Environment** [page](/instore/use-the-instore-center/environment.md#custom-fields-tab) and use the list below to add or verify the required fields.

### Custom Fields reference

Required attributes are maintained in your Project. InStore-specific Custom Fields are maintained in the InStore Center.

| Type Key | Required Attribute | Custom Field | Data type |
| --- | --- | --- | --- |
| Customer | [CUSTOMER\_PAYMENTACCOUNTIDS\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#customer_paymentaccountids_field) | \paymentAccountIds | String |
| LineItem | [LINEITEM\_FULFILLMENT\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_fulfillment_field) | \fulfillment | String |
| LineItem | [LINEITEM\_ISGIFT\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_isgift_field) | \isGift | Boolean |
| LineItem | [LINEITEM\_MISTID\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_mistid_field) | \mistId | String |
| LineItem | [LINEITEM\_PRICEOVERRIDEAPPROVER\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_priceoverrideapprover_field) | \priceOverrideApprover | String |
| LineItem | [LINEITEM\_PRICEOVERRIDECODE\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_priceoverridecode_field) | \priceOverrideCode | String |
| LineItem | [LINEITEM\_PRICEOVERRIDETYPE\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_priceoverridetype_field) | \priceOverrideType | String |
| LineItem | [LINEITEM\_PRICEOVERRIDEVALUE\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_priceoverridevalue_field) | \priceOverrideValue | String |
| LineItem | [LINEITEM\_PURCHASELINEITEM\_ID\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_purchaselineitem_id_field) | \purchaseLineItemId | String |
| LineItem | [LINEITEM\_PURCHASEORDERID\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_purchaseorderid_field) | \purchaseOrderId | String |
| LineItem | [LINEITEM\_RETURNCOMMENT\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_returncomment_field) | \returnComment | String |
| LineItem | [LINEITEM\_SALESPERSONID\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#lineitem_salespersonid_field) | \salespersonId | String |
| Cart/Order | [ORDER\_LOCATIONID\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#order_locationid_field) | \locationId | String |
| Cart/Order | [ORDER\_ORDERTYPE\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#order_ordertype_field) | \orderType | Enum |
| Cart/Order | [ORDER\_SEQUENCE\_NUMBER\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#order_sequence_number_field) | \sequenceNumber | String |
| Cart/Order | [ORDER\_USERID\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#order_userid_field) | \userId | String |
| Cart/Order | [ORDER\_WORKSTATIONID\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#order_workstationid_field) | \workstationId | String |
| Payment | [PAYMENT\_ACCOUNTNAME\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#payment_accountname_field) | \accountName | String |
| Payment | [PAYMENT\_ACCOUNTNUMBER\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#payment_accountnumber_field) | \accountNumber | String |
| Payment | [PAYMENT\_BARCODE\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#payment_barcode_field) | \barcode | String |
| Payment | [PAYMENT\_CUSTOMERNUMBER\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#payment_customernumber_field) | \customerNumber | String |
| Payment | [PAYMENT\_ISSUERID\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#payment_issuerid_field) | \issuerId | String |
| Payment | [PAYMENT\_MISTID\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#payment_mistid_field) | \mistId | String |
| Transaction | [ORDER\_EMAILTRIGGERED\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#order_emailtriggered_field) | \isEmailTriggered | Boolean |
| Transaction | [PAYMENT\_CASHROUNDING\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#payment_cashrounding_field) | \cashRounding | Boolean |
| Transaction | [TRANSACTION\_MISTID\_FIELD](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#transaction_mistid_field) | \mistId | String |

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

#### `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 POS. 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 POS. 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 POS. 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 POS. 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](/instore/customization/administration-parameters.md#tender-parameters).

#### `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 POS 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](/instore/implement-instore/integrate-with-instore/map-custom-fields.md#order-number-structure).

#### `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 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 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 a stored-value card as tender. This is the InStore ID of the stored-value 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 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 POS > **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
```

## Related pages

- [Area overview page with navigation](/instore.md)
- [Previous page: Add Types and Custom Fields to your Project](/instore/implement-instore/integrate-with-instore/types-and-custom-fields.md)
- [Next page: Use Callbacks](/instore/implement-instore/integrate-with-instore/callbacks.md)
- [Search documentation and API specs](/search.md)