Create a custom currency for loyalty points

You can create a custom currency and assign it to a price group so shoppers can see items priced in points and then use points to pay for purchases on your store.

This section describes how to create a custom currency and add it to a price group. You will also need to perform other tasks so shoppers can place orders paid for with points. For example:

You must use the Commerce REST API to create a custom currency for the points. Merchandisers then create a price group for the currency in the Commerce administration interface. Once the price group is active, shoppers can select the points-based currency to see the prices for all items in points. All items in an order must be priced in a single currency. Therefore, a shopper must use points to pay for an entire order. A shopper cannot use points to pay for only some items in an order.

The Avalara AvaTax and the Vertex O Series tax processor integrations will convert points-based orders into monetary currency to calculate tax. If you implement a points-based currency for your store and you use an external Commerce tax processor integration (other than Avalara AvaTax or Vertex O Series) to calculate taxes, you must convert the dollar amount into points and then store that conversion information in Oracle Commerce. See Configure Tax Processing for more information.

You can configure your site to display tax and shipping amounts in a monetary currency, separate from the loyalty points used for an order. For information, refer to the Understand tax and shipping calculations with loyalty programs section

To create a new currency for loyalty points, issue a POST request to the /ccadmin/v1/currencies endpoint on the administration server. Specify the values of the currency properties as a JSON map in the body of the request.

The following table describes the body of the request.

Property	Description
id	(Required) A string that specifies the ID for the currency. This value must be lowercase letters and cannot include underscores or spaces. This value cannot be a valid JDK locale, such as "en_US".
currencyCode	(Required) A string that represents the pointType of the loyalty program. This value cannot be an ISO 4217 standard currency code, for example, "USD".
symbol	(Required) A Unicode string that specifies the currency symbol. When shoppers select the points-based currency on your store, prices are displayed with this currency symbol.
displayName	(Required) A string that specifies the display name for the currency. Shoppers do not see the display name, but it appears internally, for example, in the Commerce administration interface and when you export products.
currencyType	(Required) "loyaltyPoints" is the only accepted value for currencyType. Any other value will cause the request to return an error.
fractionalDigits	A number that specifies the precision specifier (the number of decimal places) in the prices shoppers see on your store. The default value is 2.

The following example shows a sample request for creating a loyalty points currency:

POST /ccadmin/v1/currencies HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

{
"id": "points",
"currencyCode": "PTS",
"symbol": "P",
"displayName": "Frequent Shopper Bucks",
"currencyType": "loyaltyPoints",
"fractionalDigits": 0
}

If the currency is created successfully, the response body returned includes the ID for the new currency and a link to the URL used in the request. The following is a sample response:

{
  "currencyType": "loyaltyPoints",
  "symbol": "P",
  "deleted": false,
  "displayName": "PTS",
  "repositoryId": "points",
  "fractionalDigits": 0,
  "links": [
    {
      "rel": "self",
      "href": "http://myserver.example.com:7002/ccadmin/v1/currencies"
    }
  ],
  "currencyCode": "PTS",
  "numericCode": null,
}