Understand currency exchange rates

In instances where you have configured currency for a loyalty program, you may need to convert the loyalty program’s currency to a secondary monetary currency.

To do this, you must set up and maintain exchange rates between the loyalty program’s points and the secondary monetary currency.

The primary reason for creating an exchange rate is to set conversion rates between loyalty programs and the secondary currency. The exchange rate can also be used during tax calculations with Avalara AvaTax or Vertex O Series. This allows you to send order information to the tax processor in a format that the processor can use to calculate the tax. The tax value is then converted back into loyalty points and displayed in the order.

For information on configuring tax gateways, refer to Configure Tax Processors and Configure Tax Processing.

The secondary monetary currency is configured with the secondaryCurrency property when setting up a site. This indicates the currency that the site uses, such as USD. For information on creating a base currency and assigning it to a site, refer to the Associate a loyalty program price group with a site section.

Note: Exchange rates do not convert between different monetary currencies. For example, you should not configure an exchange rate between US dollars and Euros.

Exchange rates are set using the exchangerates endpoint to identify a source currency and target currency. Exchange rates are global and not site specific. There should be at least one exchange rate configured with the target currency identified in the secondaryCurrency property. Note that exchange rate settings are used only with sites that have loyalty points indicated in their price list group. For information on working with price list groups, refer to the Configure Price Groups.

Create exchange rates

When you create a site that supports loyalty points, you must create an exchange rate. You can create multiple exchange rates, but the site will determine which configuration to use when converting currency.

To create an exchange rate between currency and loyalty points, issue a POST request to the /ccadmin/v1/exchangerates 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 properties in the body of the request.

The following example shows a sample request for creating an exchange rate between a monetary currency and the loyalty program’s currency that you created in the Implement loyalty points section:

POST /ccadmin/v1/exchangerates HTTP/1.1
Authorization: Bearer <access_token>

{ 
	"sourceCurrency": "PTS",
	"targetCurrency": "USD",
	"exchangeRate": 5
}

If the exchange rate 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.

{
  "sourceCurrency": "USD",
  "targetCurrency": "PTS",
  "exchangeRate": 5,
  "id": "10001"

}

The price of the points-based order is converted to the secondary monetary currency for the site, using the corresponding exchange rate. The value that the tax processor calculates is converted from monetary currency back into points using the same exchange rate.

If you are using the External Tax Calculation webhook to integrate with an external tax processor, the tax call is made with or without currency conversion depending on how price list group has been configured. This allows the external tax processor to use the correct logic.

Once the conversion is complete, the exchange rate is recorded and used for subsequent operations, such as returns and exchanges. Once the tax value in monetary currency is returned by the tax processor, it is also stored so that it may be passed to order management systems as part of a Submit and Return Request webhook.