Enabling the AR Document Tax and Total to Be Displayed in an Additional Currency

If you trade internationally, you and your resellers may want the total and tax values of invoices and other AR documents to be displayed in a local currency. You can configure CloudBlue Commerce to display the AR document total and tax values in a single additional currency for your immediate resellers and customers in email notifications and PDF format. The values are calculated based on the exchange rate that you configure for the secondary currency. The exchange rate is also included in email notifications and PDF documents.

After you enable the feature, your power resellers of any level also can configure a single additional currency in RCP and use the feature for their customers.

For the AR Document Tax and Total to be displayed in an additional currency:

  • Step 1: Activate the feature.
  • Step 2: Configure the exchange rate.
  • Step 3: Configure an email notification template.

Step 1: Activate the Feature

To enable the feature:

  1. Go to CloudBlue Commerce Billing DB using SSH.
  2. Enable the feature by adding the following line to the Features table:

    insert into "Features" values('FEA_SecondaryCurrency', '', '', 1, 0 ,0);

    Note: The command sets the IsActive column value to "1" for the feature.

As a result, a link to a new configuration page, Secondary Currency Settings, will be displayed in the PCP and RCP UI at Billing > System > Settings > System > Notifications.

Step 2: Set the Exchange Rate Between the Primary and the Secondary Currency

Important: You can configure only one secondary currency for your account. When configured, the secondary currency is effective only for your direct customers and resellers. If the feature is enabled for you, it is also enabled for your resellers, who also can configure their own secondary currency.

To configure the exchange rate between the primary and the secondary currency:

  1. In the control panel, go to Billing > System > Settings > System > Notifications > Secondary Currency Settings.
  2. Click Edit. Set the Currency Code and Exchange Rate fields as necessary. Save the changes.

Step 3: Configure Email Notifications to Include AR Document Tax and Total in an Additional Currency

The capability is available with the help of the following placeholders:

  • @@Secondary_Currency_Code@: displays the international currency code in notification templates
  • @@Secondary_Currency_Rate@: displays the secondary-to-primary currency exchange rate in notification templates
  • @@Secondary_Currency_Tax@: displays the AR document tax amount in the secondary currency
  • @@Secondary_Currency_Total@: displays the AR document total amount in the secondary currency

For CloudBlue Commerce to display AR document Tax and Total in two currencies in PDF documents and email notifications, add the new placeholders to the ARDoc Details subtemplate:

  1. In the control panel, go to Billing > System > Settings > System > Notifications > Notification Templates.
  2. Find and click ARDoc Details. Switch to the HTML tab (or Plain Text tab). Click Edit.
  3. Add the new placeholders to the Tax_Details_List dataset and after the Total line.

    For example, add lines:

    <p>@@TaxDetail_Tax_Name@ @@TaxDetail_Tax_Rate@ @@Secondary_Currency_Code@ @ @@Secondary_Currency_Rate@ @@Secondary_Currency_Tax@</p>

    and

    <p><strong>Total: @@Secondary_Currency_Code@ @ @@Secondary_Currency_Rate@ @@Secondary_Currency_Total@</strong></p>

    in the following way:

    ##Tax_Details_List#
    <p>@@TaxDetail_Tax_Name@ @@TaxDetail_Tax_Rate@: @@Cust_Account_Currency_Abbreviation@ @@TaxDetail_Tax_Amount@</p>
    <p>@@TaxDetail_Tax_Name@ @@TaxDetail_Tax_Rate@ @@Secondary_Currency_Code@ @ @@Secondary_Currency_Rate@ @@Secondary_Currency_Tax@
    ##/Tax_Details_List#
    <strong>Total: @@Cust_Account_Currency_Abbreviation@ @@Total@</strong>
    <p><strong>Total: @@Secondary_Currency_Code@ @ @@Secondary_Currency_Rate@ @@Secondary_Currency_Total@</strong></p>
  4. Save the changes.

Limitations

  • The AR document tax and total in a secondary currency can be displayed only in email notifications and PDF documents and are not visible in the UI. In the UI, the AR document tax and total are displayed in the primary currency set for the system.
  • When an invoice or a notification is re-generated, it includes the current currency exchange rate, which may be different from the original exchange rate that was effective when the document was initially generated.
  • The new placeholders are available but inactive after the upgrade. They can be used only after the feature is activated.