Create custom properties for addresses

You can use the Retail Digital Commerce REST web services APIs to add custom properties to shopper and account addresses.

This section applies to Open Storefront Framework (OSF).

See Use the REST APIs for information you need to know before using the services. Note that the view models for addresses support custom properties, but widgets included with Retail Digital Commerce require customization to access these properties.

View the contactInfo item type

Addresses are stored internally as instances of the contactInfo item type. You can view this item type with the following call:

GET /ccadmin/v1/itemTypes/contactInfo  HTTP/1.1
Authorization: Bearer <access_token>

The following example shows a portion of the response representing one of the contactInfo properties. Each property has a group of attributes whose values control the behavior associated with the property:

...
{
   "length": 254,
   "label": "City",
   "type": "shortText",
   "required": false,
   "searchable": false,
   "writable": true,
   "internalOnly": false,
   "uiEditorType": "shortText",
   "default": null,
   "audienceVisibility": "all",
   "localizable": false,
   "textSearchable": false,
   "id": "city",
   "dimension": false,
   "editableAttributes": [
      "internalOnly",
      "default",
      "audienceVisibility",
      "textSearchable",
      "label",
      "dimension",
      "required",
      "searchable",
      "multiSelect"
   ],
   "multiSelect": null
}
...

You can use the updateItemType endpoint to modify the contactInfo item type:

• Modify existing properties by changing the values of their attributes.
• Create custom properties by specifying their attributes.

See Settable attributes of shopper type properties for descriptions of these attributes.

Add Custom Properties to the contactInfo Item Type

You can use the updateItemType endpoint in the Commerce Admin API to add custom properties to the contactInfo item type. When you add a custom property to the contactInfo item type, the property is added to addresses in profiles, as well as in other data objects that include addresses, such as accounts and orders. The property is not added to inventory locations, however.

The ID of a custom property must include the underscore character (_). This ensures that the ID will not conflict with any properties that Retail Digital Commerce adds to addresses in the future. The updateItemType endpoint produces an error if you attempt to create a custom property without an underscore in its ID.

The following example illustrates using the updateItemType endpoint to add a custom property to addresses. Note that the request header must specify the x-ccasset-language value:

PUT /ccadmin/v1/itemTypes/contactInfo  HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en

{
  "id": "contactInfo",
  "specifications": [
    {
       "id": "sales_region",
       "label": "Sales Region",
       "type": "shortText",
       "uiEditorType": "shortText",
       "internalOnly": false,
       "required": false,
       "default": null
    }
  ]
}

The response includes the custom property you added:

...
  {
           "length": 254,
           "label": "Sales Region",
           "type": "shortText",
           "required": false,
           "searchable": false,
           "writable": true,
           "internalOnly": false,
           "uiEditorType": "shortText",
           "default": null,
           "audienceVisibility": null,
           "localizable": false,
           "textSearchable": false,
           "id": "sales_region",
           "dimension": false,
           "editableAttributes": [
               "internalOnly",
               "default",
               "audienceVisibility",
               "textSearchable",
               "label",
               "dimension",
               "required",
               "searchable",
               "multiSelect"
           ],
           "multiSelect": null
       }
...