Customize address formats using the API

Understand customized address formats

Some countries require a county or a district in addition to the default address, city, state, postal code and phone number fields. Creating custom address formats allows you to create address formats that change based upon the shopper’s country locale. Using the API, you can map custom fields to the administration interface. This also allows you to work with address verification services and ensure that your address customizations are in line with these services.

Address customizations can contain fields with variable label text. These fields can have different requirements and default values. Once you have created the custom address, you associate it with a specific country or countries so that it is used only on storefronts (and administration and agent interfaces) with that locale. When a shopper from that locale sees the site, the address format is changed to match the format identified for that locale.

You can customize addresses that are found on profiles, accounts, account registration requests, as well as payment and shipping group pages. Addresses found on credit card, inventory location or the Ship from Warehouse location address in the tax processing setting pages cannot be customized.

Custom address formats are defined by creating a server-side extension (SSE). The server-side extension allows you to specify the values for the address properties. Each locale can have an individual address customization, or can share customizations. Note that multiple countries can share the same address format, but must have different values for the properties. Server-side extensions also allow you to upload a file containing multiple address formats in bulk using a JSON format, or export, modify or re-import address formats. For general information on working with extensions, refer to the Developing Widgets guide.

Before you can create custom addresses, you must implement a server-side extension from the Commerce Cloud administration server. See Use server-side extensions in Using Oracle Commerce for details on how to download server-side extensions. If you are using one of Commerce’s default tax processors, it is also suggested that you verify that any address modifications you want to make will continue to work with the tax processor validation.

Note: Because Avalara and Vertex Tax Processors do not support adding custom properties, you cannot create customized address formats for either of these integrations.

Server-side extensions define REST endpoints that allow you to customize countries and region/states addresses. Each country and region/state also has a localizable display name.

Work with a server-side extension for customized addresses

Oracle Commerce Cloud provides an example server-side extension that creates customized address formats. The example contains country-specific address formats, which you can use as a template for creating your own address formats. Address properties that are defined using this SSE are stored as custom address properties, which behave just like any other custom address properties. These address properties are included in all APIs and web hooks that use the address property, with the exception of those addresses on credit cards, inventory pages or tax processing ship-from-warehouse location addresses.

The server-side extension references a widget that specifies the address formats maintained by JSON files. These JSON files include metadata files, resource bundles and files that map values to each of the properties.

When you download the server-side extension, it is copied locally to your system in a ZIP file. Each ZIP file contains the following files:

Package.json – This file contains the metadata information for the server-side extension. It contains the main entry point, name and public URLS, as well as the description and devDependencies and files that are contained in the extension.
Index.js – This file calls the HTTP requests and responses.
Readme.md – A file that describes the server-side extension’s classes and endpoints and includes information on installing and extending the extension.

The example SSE contains the following directories:

/lib – This directory contains the class that processes address metadata, which can be extended to call endpoints or make modifications to value mappings. It also contains module constants and address format, metadata and value mappings for three different example address locations for the United Arab Emirates (UAE), the Unites States (US) and Singapore (SG).
/node_modules – This contains a library that wraps the logging utility and should be copied into the /node_modules directory of the server-side extension.
/out – This directory contains the output, including styles and the HTML that displays the JavaScript documentation for the SSE.

Define country-specific properties using metadata

The server-side extension metadata allows you define the properties that are included in the address customization. Properties are specific to the country they display. The metadata also allows you to list the order in which the properties are displayed within the administration interface.

Properties can be identified as required or as an internal-only property, and can include default values.

For a property to be displayed with a localized string, the label field for the property must be configured as resources.propertyName. If the resources prefix is not used in the label field, the property name will not be localized. The following is an example of a United States-specific address metadata JSON file. For example, note that the properties label field value is prefixed with resources. This ensures that the field is localized.

Property types allow you to indicate if the property is shortText, richText, date, checkbox or enumerated. Enumerated address properties can be related to one another, which lets you provide a list of values that are displayed across related properties. Although multiple countries can share the same address format, they must have different values for any enumerated properties.

The following is from the Metadata.json file of the SSE example:

{
   "properties": {
     "address1": {
       "id": "address1",
       "type": "shortText",
       "uiEditorType": "shortText",
       "label": "resources.addressLine1",
       "validations": [
         {
           "type": "required",
           "value": true
         },
         {
           "type": "maxLength",
           "value": 60
         }
        ]
       },
     "address2": {
       "id": "address2",
       "type": "shortText",
       "uiEditorType": "shortText",
       "label": "resources.addressLine2",
       "validations": [
        {
           "type": "required",
           "value": false
         },
         {
           "type": "maxLength",
           "value": 60
         }
       ]
     },
     "postalCode": {
       "id": "postalCode",
       "type": "shortText",
       "uiEditorType": "shortText",
       "label": "resources.postalCode",
       "validations": [
         {
           "type": "required",
           "value": true
         },
         {
           "type": "maxLength",
           "value": 10
         },
         {
           "type": "regex",
           "pattern": "^[0-9]{5}([ -][0-9]{4})?$"
          }
        ]
     },
     "state": {
        "id": "state",
        "type": "singleSelect",
        "uiEditorType": "singleSelect",
        "label": "resources.state",
        "parent": "country",
        "validations": [
          {
            "type": "required",
            "value": true
          }
        ]
     },
     "city": {
        "id": "city",
        "type": "shortText",
        "uiEditorType": "shortText",
        "label": "resources.city",
        "parent": "state",
        "validations": [
          {
            "type": "required",
            "value": true
           }
         ]
     },
     "phoneNumber": {
         "id": "phoneNumber",
         "type": "shortText",
         "uiEditorType": "shortText",
         "label": "resources.phoneNumber",
         "validations": [
           {
             "type": "required",
             "value": false
           },
           {
             "type": "maxLength",
             "value": 15
           },
           {
             "type": "regex",
             "pattern": "^[0-9()+ -]+$"
           }
        ]
     }
   },
   "propertiesOrder": [
      [
        "address1"
      ],
      [
        "address2"
      ],
      [
        "city",
        "state"
      ],
      [
        "postalCode",
        "phoneNumber"
      ]
    ]
}

Notice that the JSON file also identifies the order in which properties will be displayed to the shopper. In the SSE example, the properties included in the US-specific metadata are mapped to the following default properties and in the order in which they will be displayed:

Order No.	Property	Type	Required	Mapped to Default Property	Parent Property
1	`address1`	`ShortText`	Yes	`address1`	N/A
2	`address2`	`ShortText`	No	`address2`	N/A
3	`city`	`ShortText`	Yes	`city`	N/A
4	`state`	`SingleSelect`	Yes	`state`	`country`
5	`postalCode`	`ShortText`	Yes	`postalCode`	N/A
6	`phoneNumber`	`ShortText`	No	`phoneNumber`	N/A

For contrast, the following is the SSE example of a metadata mapping for the United Arab Emirates (UAE):

Order No.	Property	Type	Required	Mapped to Default Property	Parent Property
1	`addressLine1`	`ShortText`	Yes	`address1`	N/A
3	`area`	`SingleSelect`	Yes	`city`	N/A
4	`emirate`	`SingleSelect`	Yes	`state`	N/A
5	`zipPostalCode`	`ShortText`	Yes	`postalCode`	`country`
6	`phoneNumber`	`ShortText`	N/A	`phoneNumber`	N/A

Understand resource bundles

The SSE contains sample address formats. You can also upload a file that contains multiple address formats with the associated country mapping. Additionally, you can export address formats, modify or populate them and then import them.

These JSON files provide the locale resources for country-specific properties. The resource bundle JSON file for the US-specific metadata might be:

{
   "addressLine1": "Address Line 1",
   "addressLine2": "Address Line 2",
   "state": "State/Region",
   "city": "City",
   "postalCode": "Zip/Postal Code",
   "phoneNumber": "Phone Number"
}

While the locale resources for Spain-specific metadata might be:

{
   "addressLine1": "Dirección Line 1",
   "addressLine2": "Dirección Line 2",
   "state": "Estado / Región",
   "city": "Ciudad",
   "postalCode": "Código postal",
   "phoneNumber": "Número de teléfono"
}

Understand value mappings

Value mappings are JSON files that provide a value array for the country-specific properties. These mappings allow you to identify specific address data, such as city or state values.

The following is an example of state.json in the UAE-specific value mapping file. Note that the displayName field value is prefixed with resources, ensuring that the display name is localized.

{"AE" : [
    {
      "regionCode": "AE-AZ",
      "displayName": "resources.Abu Dhabi",
      "repositoryId": "AE-AZ",
      "abbreviation": "AZ"
    },
    {
      "regionCode": "AE-AJ",
      "displayName": "resources.Ajman",
      "repositoryId": "AE-AJ",
      "abbreviation": "AJ"
    },
    {
      "regionCode": "AE-DU",
      "displayName": "resources.Dubai",
      "repositoryId": "AE-DU",
      "abbreviation": "DU"
...

Value mappings are also supported by resource files. The value mapping resource file provides locale information when the resources prefix is added to the field. The following is the example of the UAE-specific ar.json file, which allows the displayName field to show the localized text:

{
  "Abu Dhabi": "أبو ظبي",
  "Ajman": "عجمان",
  "Dubai": "دبي",
  "Fujairah": "الفجيرة",
  "Ras al-Khaimah": "رأس الخيمة",
  "Sharjah": "الشارقة",
  "Umm al-Quwain": "ام القيوين",
  "United Arab Emirates": "الإمارات العربية المتحدة"
}

Associate endpoints

The address customization server-side extension uses endpoints to exchange address information. Use the /addresscustomformat/getAddressMetadata and /getAddressPropertyValue endpoints to get the address metadata and properties respectively. The address formatting endpoints return the address information with the specified parameters. Each country, region and state has a localizable display name. These properties become available for profiles, accounts, self-registration and order addresses, and can be displayed in the administration interface. Note that custom address properties do not appear in the address list of the Account interface and the Registration Request interface.

The example server-side extension for address formats uses custom REST endpoints, which use the prefix /ccstorex/custom. For example:

/ccstorex/custom/v1/addresscustomformat/getAddressMetadata

The /addresscustomformat/getAddressMetadata endpoint gets the metadata for the country or context that you select. Issue a GET command to obtain the address metadata. For example:

GET /ccstorex/custom/v1/addrescustomformat/getAddressMetadata?contextId=US

You can use the /addresscustomformat/getAddressPropertyValue endpoint to obtain any address property’s value. To do this, issue a GET command. Note that the contextId, propertyName and parentContextID query parameters are mandatory.

/ccstorex/custom/v1/addresscustomformat/getAddressPropertyValue?contextId=US&parentContextId=US&locale=en&propertyName=state

The locale parameter can be passed in using a query parameter or the X-CCAsset-Language request header. If you do not pass in the locale, the system will use the default locale passed in by the server-side extension. The response may be something similar to the following:

[
   {
     "regionCode": "US-AL",
     "displayName": "Alabama",
     "repositoryId": "US-AL",
     "abbreviation": "AL"
   },
   {
     "regionCode": "US-AK",
     "displayName": "Alaska",
     "repositoryId": "US-AK",
     "abbreviation": "AK"
   },
...

Understand the address customization widget

You can display the address customizations to your shoppers by employing it in a widget. The checkout Address Book customization widget example allows you to present your shoppers with a list of countries. The widget displays the address properties included in the associated address format for each locale. The widget allows you to create custom fields, as well as different label text for each field. You can also determine if your customized fields are required or not, as well as provide a default value for each field. For each enumerated property, the widget displays a drop-down of the configured options. Any properties that are hierarchical display the child property options that are configured for the selected parent value.

The following are portions of the changes made in the example customized checkout-address-book.js widget file.

Review the customized widget example

The first thing the example shows is how to add the ccRestClient, viewModels/dynamicProperty and ccstoreConfiguration parameters to the dependencies and model definitions.

Note: Custom address properties are available to Storefront using the view models for contact addresses, account addresses, order details and submission of registration request.

For example:


//-------------------------------------------------------------------
// DEPENDENCIES
//-------------------------------------------------------------------
   ['knockout', 'viewModels/address', 'ccConstants', 'pubsub',
    'koValidate', 'notifier', 'ccKoValidateRules', 'storeKoExtensions',
    'spinner', 'navigation', 'storageApi', 'CCi18n','ccRestClient',
    'viewModels/dynamicProperty', 'ccStoreConfiguration'   ],
//------------------------------------------------------------------- 
// MODULE DEFINITION
//-------------------------------------------------------------------
function(ko, Address, CCConstants, pubsub, koValidate, notifier,
   rules, storeKoExtensions, spinner, navigation, storageApi, CCi18n, ccRestClient,
       DynamicProperty, CCStoreConfiguration) {

The example then adds the following observables:

shippingAddressproperties: ko.observableArray([]),
 shippingAddressPropertiesOrder: ko.observableArray([]),
 addressConfiguredInSSE: ko.observable(false),

For example:

// Switch between ‘view’ and 'edit' views
isUsingSavedAddress: ko.observable(false),
isSelectingAddress: ko.observable(false),
billingAddressEnabled: ko.observable(),
addressSetAfterWebCheckout: ko.observable(false),
addressSetAfterOrderLoad: ko.observable(false),
showPreviousAddressInvalidError: ko.observable(false),
previousSelectedCountryValid: ko.observable(false),
shippingAddressBook: ko.observableArray().extend({ deferred: true }),
shippingAddressProperties: ko.observableArray([]),
shippingAddressPropertiesOrder: ko.observableArray([]),
addressConfiguredInSSE : ko.observable(false),
loadPersistedShipping : ko.observable(false),

The example then adds the definition to the default checkoutAddressBook widget. The first function is the populateMetadataForContextConfiguredInSSE, which initiates an SSE endpoint to retrieve the metadata for a specific locale. Once the widget has performed various validation functions, it uses the populateSelectedCountryMetadata.