The Custom Fields API is only available for B2B Buyer Portal. Authorization from the Commerce Engineer of the account is required for use.

The Custom Fields integration enables B2B stores to capture additional business-specific information during checkout. This guide explains how to use the Custom Fields API to define, manage, and apply custom fields such as Cost Center, PO Number, or Location to orders.

The integration supports three main operations:

• Custom field settings: Define the structure and behavior of custom fields for a contract.
• Custom field values: Create predefined values for fields of type option.
• OrderForm application: Apply custom field values to shopping carts during checkout.

The custom fields integration works in three phases: configuration, value assignment, and checkout application.

Example flow:

1. Create a custom field setting for a contract:

   
   

   _10

   POST /api/dataentities/customFieldSettings/documents?_schema=v2

   
   

2. Create values for the custom field (if type is option):

   
   

   _10

   POST /api/dataentities/customFieldValues/documents?_schema=v2

   
   

3. Apply the custom field to an orderForm during checkout:

   
   

   _10

   PUT /api/checkout/pub/orderForm/{orderFormId}/customFields/{entityType}/{entityId}

   
   

Custom fields can be applied at three levels: order (entire order), item (individual cart items), or address (specific shipping addresses).

Use the POST Create custom field settings endpoint to create the configuration for a custom field associated with a specific contract. You define the field name, type, level, and whether it's required.

Use the GET Get custom field settings endpoint to retrieve all custom field settings configured for a specific contract. Use the _where parameter to filter by contractId.

Use the POST Create custom field value endpoint to create a value for custom fields of type option. Each value is associated with a specific custom field and contract.

Use the GET Search custom field values to retrieve all values for a specific custom field. Use the _where parameter to filter by contractId and customFieldId.

Use the PUT Create or update custom field in orderForm endpoint to apply a custom field value to an orderForm during checkout. The linkedEntity.type determines the level (order, item, or address) and linkedEntity.id identifies the specific entity.

Use the PUT Create or update custom fields in orderForm (batch) endpoint to apply multiple custom fields to an orderForm in a single request. Use this when you need to set fields at different levels simultaneously.

Use the DELETE Delete custom field from orderForm endpoint to remove a specific custom field from an orderForm.

Custom fields support different levels and types to accommodate various business requirements:

Level	Description	Example use cases
order	Applied to the entire order	PO Number, Project Code
item	Applied to individual cart items	Cost Center, Budget Code
address	Applied to specific shipping addresses	Delivery Instructions, Dock ID

Type	Description	Example use cases
text	Free-form text input	Notes, reference numbers
number	Numeric values only	Quantities, numeric codes
option	Predefined list of values	Cost centers, departments

For Budgets integration, only custom fields of type option are supported. This allows using the value ID for matching, enabling value renaming without breaking budget configurations.

When configuring budgets that use custom fields, use entityType as CUSTOMFIELD and the custom field value id (DocumentId) as the entityId.

When configuring buying policies, use the custom field value id in boolean expressions instead of the actual value. This allows renaming values without breaking existing policies.

The Default Values integration allows you to pre-configure which custom field value should be automatically selected at checkout for each organizational unit. When a buyer logs in, the system automatically loads the configured default values, eliminating the need for manual selection.

How it works

The integration works in two phases:

1. Configuration phase: The organization administrator defines which custom field values should be used as defaults for each organizational unit (org unit, contract, or user).
2. Consumption phase: At buyer login, the shopper-session app fetches the configured default values and automatically applies them to checkout.

Entity format

To configure a custom field as a default value, use the following format in the defaultValues array:

Field	Description
entity	Entity type identifier. For custom fields, use customFieldValues/ followed by the custom field setting ID (obtained when creating the field configuration).
entityValueId	ID of the custom field value to be used as default (DocumentId returned when creating the value).

Request example - Create default values with custom field

In this example, we configure the Cost Center "Marketing" as the default value for the organizational unit orgUnit-456:

In this example, 89f1da93-6917-4cbf-894e-1f1399682826c is the ID of the "Cost Center" custom field setting and 07d12677-08d8-11f0-b37f-e1ae31409099 is the ID of the "Marketing" value.

Response example

Update default values

To update the default values of an existing organizational unit:

Remove default values

To completely remove the default values of an organizational unit:

Complete integration flow

The diagram below illustrates the complete flow from creating the custom field to applying the default value at checkout:

Default Values permissions

The following License Manager permissions are required for Default Values operations:

Operation	Required resources
Create default values	Insert or update documents (not remove), Full access to all documents, or Master Data administrator
Read default values	Read-only documents, Insert or update document (not remove), Full access to all documents, or Master Data administrator
Update default values	Insert or update documents (not remove), Full access to all documents, or Master Data administrator
Delete default values	Full access to all documents or Master Data administrator

Only custom fields of type option are supported for default value configuration. This ensures that the value ID is used for matching, allowing values to be renamed without breaking configurations.

If a custom field's name or value is altered after an order has been placed, these changes will not be reflected in the existing order. The order retains the original values.

The following License Manager resources are required:

Operation	Required resources
Create/Update settings or values	Insert or update documents (not remove), Full access to all documents, or Master Data administrator
Read settings or values	Read-only documents, Insert or update documents (not remove), Full access to all documents, or Master Data administrator
Delete settings or values	Full access to all documents or Master Data administrator
OrderForm operations	Read Shopping Cart

All resources belong to the Dynamic Storage product, except OrderForm operations which belong to the Checkout product.