Adding support for a currency to HCL Commerce

You can use REST API to update your environment database to add support for a new currency to HCL Commerce. By adding the support for the currency, you can then add support for the currency to specific stores so that shoppers can view prices in that new currency.

Additionally, you can use REST API to define the currency format for how the currency is displayed and define how to convert prices in other currencies to your new currency. You can also use REST API to create search facets to represent prices in the new currency on store pages.

Before you begin

When you are adding a currency, you need to know and use the ISO 4217 standard currency code for the currency. For more information about these standards, see

ISO 4217

Procedure

Compose the REST API request to add the currency within HCL Commerce.
When you are adding descriptions you need to use the following administrative REST API:
- Currencies (https://localhost:443/rest/admin/v2/currencies)
The body of the call to add the currency can resemble the following example, which adds the Indian Rupee (currency code of INR) currency.
```
{
  "id\": \"{{code}}\",
  "numericCurrencyCode\": {{numericCode}},
  "currencyExponent\": -2
}
```
To compose the API call you need the following details for identifying the store and currency:
- The currency code. This code is the 3-character ISO 4217 code for the currency, such as USD for the United States Dollar currency.
- The numeric currency code. This code is the numeric ISO 4217 code for the currency, such as 840 for the United States Dollar currency.
- The currency exponent, which is the exponential value by which a sub-unit of the currency (such as cents) is multiplied to get the main currency unit. For example, for the United States Dollar currency you multiply the number of cents by 10 to the power -2 to get the number of dollars.
Compose the REST API request to add the descriptive information, such as a display name, for the new currency.
This description is used by shoppers and business users to identify the currency. This descriptive information can be visible in the storefront when users are browsing the store. The descriptive information also displays for the currency within Management Center.
When you are adding descriptions you need to use the following administrative REST API:
- Currency descriptions (https://localhost:443/rest/admin/v2/currency-descriptions_admin)
The body of the call to add the currency description can resemble the following body structure:
```
{
  \"code\": \"{{code}}\",
  \"languageId\": {{langId_en}},
  \"description\": \"{{description}}\"
}
```
To compose the API call you need the following details for identifying the store and currency:
- The currency code.
- The ID for identifying the language for the description within HCL Commerce.
Compose the REST API request for defining how to convert prices from another currency to your new currency.
When you are adding currency conversion rate details you need to use the following administrative REST API:
- Currency conversions (https://localhost:443/rest/admin/v2/currency-conversions_admin)
To compose this API call you need details for identifying both currencies and for defining the conversion rate. The body of the call to add the currency conversion rate can resemble the following body structure:
```
{   
  \"storeId\": {{catalogAssetStoreId}},
  \"fromCurrency\": \"USD\",
  \"toCurrency\": \"{{code}}\",
  \"conversionFactor\": 2.3215,
  \"multiplyOrDivide\": \"M\",
  \"bidirectional\": \"Y\",
  \"updatable\": \"Y\"
}
```
Compose the REST API request for defining how the currency is to be formatted for display on the storefront.
When you are adding currency format information you need to use the following administrative REST API:
- Currency formats (https://localhost:443/rest/admin/v2/currency-format_admin)
To compose this API call you need details for identifying the currency and the currency format. The body of the call for adding the currency format can resemble the following body structure:
```
{
  \"storeId\": {{catalogAssetStoreId}},
  \"currency\": \"{{code}}\",
  \"roundingMultiple\": 1,
  \"numberUsg\": -1,
  \"roundingMethod\": \"R\",
  \"decimalPlaces\": 2,
  \"minimumApproveAmount\": null
}
```

Compose the REST API request for defining the currency format descriptive information, such as for defining the symbol for the currency.

When you are adding currency format descriptions you need to use the following administrative REST API:

Currency formats (https://localhost:443/rest/admin/v2/currency-format-descriptions)

To compose this API call you need details for identifying the currency and language. The body for the call to add the descriptive information can resemble the following body structure:


{
  \"languageId\": {{langId_en}},
  \"currencySymbol\": \"{{symbol}}\",
  \"customizedCurrencyCode\": null,
  \"currencyPrefixPositive\": \"{{symbol}}\",
  \"currencyPrefixNegative\": \"-{{symbol}}\",
  \"currencySuffixPositive\": null,
  \"currencySuffixNegative\": null,
  \"displayLocale\": null,
  \"radixPoint\": null,
  \"groupingCharacter\": null,
  \"numberPattern\": \"#,##\",
  \"description\": \"{{description}}\",
  \"storeId\": {{catalogAssetStoreId}},
  \"currency\": \"{{code}}\",
  \"numberUsg\": -1        
}

Compose the REST API request for defining the search fields for the currency.
By adding the search fields, you can create search facets based on the prices in the currency so that storefront users can filter search results by prices in the currency.
When you are adding the search fields, you need to use the following administrative REST API:
- Search fields (https://localhost:443/rest/admin/v2/search-field_admin)
To compose this API call you need details for identifying the search index and currency. The body for the call to add the search field can resemble the following body structure:
```
{
  \"id\": 10001,
  \"indexId\": \"0\",
  \"indexType\": \"CatalogEntry\",
  \"identifier\": \"_cat.OfferPrice_{{code}}\"
}
```
Compose the REST API request for defining the properties for the currency search field to create a search facet for the currency.
These properties define the price ranges that will be used as search facets. When you are adding the search field properties, you need to use the following administrative REST API:
- Search field properties (https://localhost:443/rest/admin/v2/search-field-property_admin)
To compose this API call you need details for identifying the search field. The body for the call to add the field properties can resemble the following body structure:
```
{
  \"fieldId\": 10001,
  \"property\": \"facet\",
  \"fieldName\": \"price_{{code}}:{* TO 100];{100 TO 200];{200 TO 300];{300 TO 400];{400 TO 500];{500 TO *}\"
}
```
Compose the REST API request for defining the properties for the currency search facets.
When you are adding the search facet properties, you need to use the following administrative REST API:
- Search facet properties (https://localhost:443/rest/admin/v2/facet-property_admin)
To compose this API call you need details for identifying the search facet. The body for the call to add the facet properties can resemble the following body structure:
```
{
  \"id\": 10001,
  \"attributeId\": null,
  \"fieldId\": 10001,
  \"storeId\": 0,
  \"selection\": 0,
  \"sortOrder\": 0,
  \"searchDisplay\": 1,
  \"zeroDisplay\": 0,
  \"maxDisplay\": 20,
  \"sequence\": 0,
  \"field1\": null,
  \"field2\": null,
  \"field3\": null,
  \"groupId\": 0
}
```
Compose the REST API request for defining the descriptive information for the currency search facets.
When you are adding the search facet descriptions, you need to use the following administrative REST API:
- Search facet properties (https://localhost:443/rest/admin/v2/facet-description_admin)
To compose this API call you need details for identifying the search facet for a specific language. The body for the call to add the facet description can resemble the following body structure:
```
{
  \"facetId\": 10001,    
  \"languageId\": {{langId_en}},
  \"name\": \"Price ({{code}})\",
  \"description\": \"Price-{{code}}\",
  \"field1\": null,    
  \"field2\": null,
  \"field3\": null
}
```
Run your REST API calls add the currency to HCL Commerce.
To run your REST API calls, you can bundle your REST calls into a JSON collection with the API calls for adding the currency to a store to run all the calls in sequence. The following collection shows how to bundle the API calls for adding a currency.
- API collection for adding a currency
To use this collection, you need to define the environment variables for the API. The API calls within the collection are structured with variables. The values that are used for the variables can be included within a separate JSON file. The following file includes sample values for defining the Indian Rupee (INR) currency.
- API collection environment variables for adding a currency
Replace the sample values that are set within the file with the values for the stores and the currency that you are adding to your environment. You can then use the collection and values files to run the API requests to add the currency.