Data Source Objects that Support Foreign Currency Conversion

You can export currency conversion data for the following data source objects:

• Credit Balance Adjustment

• Discount Applied Metrics

• Invoice - Currency conversion data is provided for posted invoices only.

• Invoice Adjustment

• Invoice Item - Currency conversion data is provided for items in posted invoices only.

• Invoice Item Adjustment

• Invoice Payment

• Order Line Item

• Payment

• Refund

• Refund Invoice Payment

• Revenue Schedule Item

• Revenue Schedule Item Invoice Item

• Revenue Schedule Item Invoice Item Adjustment

• Taxation Item - Currency conversion data is provided for items in posted invoices only.

• Rate Plan Charge

If you enable the Invoice Settlement feature, you can also export currency conversion data for the following data source objects:

• Credit Memo

• Credit Memo Item

• Credit Memo Application

• Credit Memo Application Item

• Credit Memo Part

• Credit Memo Part Item

• Debit Memo

• Debit Memo Item

• Payment Part

• Payment Part Item

• Payment Application

• Payment Application Item

• Refund Part

• Refund Part Item

• Refund Application

• Refund Application Item

• Credit Taxation Item

• Debit Taxation Item

• Revenue Schedule Item Credit Memo Item

• Revenue Schedule Item Debit Memo Item

You can include currency conversion data only for the base object of a data source export, not its joined objects. For example, if you want to export foreign currency conversion data for the Invoice Item object, you must perform a data source export on the Invoice Item data source.

Convert Transaction Amounts Into Your Home Currency

You can use the Zuora UI, SOAP API, and AQuA API to create data source exports that include transaction amounts converted into your home currency.

Prerequisites

In Finance Settings > Manage Currency Conversion , ensure that you have:

• Configured your home currency

• Selected the Automatically include additional Currency Conversion information in data source exports checkbox.

Creating the Data Source Export

To automatically include your home currency conversion data in a data export, select the Amount field of the base object in the data source export. For example, if you export data from the Payment data source, select the Amount field from the Payment object.

To see which field you must select for each data source object, refer to the "Amount" column in the section below called "Values for the Foreign Currency Conversion Fields".

Convert Transaction Amounts Into Any Currency

You can use the Zuora SOAP API and AQuA API to create data source exports that include transaction amounts converted into one or more specified currencies. This feature is not available when creating exports from the Zuora UI.

Prerequisites

There are no prerequisites.

Creating the Data Source Export Using the SOAP API

When creating a data source export using the SOAP API :

• Add the ConvertToCurrencies field to the create() call and specify the currencies you want amounts to be converted into. You can specify any number of currencies. Specify the currencies using their ISO currency codes and separate each currency with a comma.

• Select the Amount field of the base object in the data source export.

• Ensure that you are using WSDL version 78 or later.

The following example SOAP API request specifies that conversion data for British Pound Sterling (GBP) and Japanese Yen (JPY) be included in the data source export.

...
<ns1:create xmlns:ns1="http://api.zuora.com/">
    <ns1:zObjects xsi:type="ns2:Export" xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
          <ns2:Format>csv</ns2:Format>
          <ns2:Query>select Amount, CreatedDate from Invoice</ns2:Query>
          <ns2:ConvertToCurrencies>GBP,JPY</ns2:ConvertToCurrencies>
    </ns1:zObjects>
</ns1:create>
...

Creating the Data Source Export Using the AQuA API

When creating a data source export using the AQuA API :

• Add the convertToCurrencies field to the request and specify the currencies you want amounts to be converted into. You can specify any number of currencies. Specify the currencies using their ISO currency codes and separate each currency with a comma.

• Select the Amount field of the base object in the data source export.

• Set the type field to "zoqlexport", otherwise an error is returned. This feature is not supported for type "zoql".

• Ensure that you are using API version 78 or later. You can do this by specifying the the API version in the apiVersion field. Or, if you do not pass in the apiVersion field, the latest API version is used by default.

The following example AQuA API request specifies that conversion data for British Pound Sterling (GBP) and Japanese Yen (JPY) be included in the data source export.

{
"format" : "csv",
"version" : "1.2",
"name" : "MyExampleExport",
"encrypted" : "none",
"useQueryLabels" : "true",
"partner" : "MyPartnerID",
"project" : "123456",
"dateTimeUtc" : "true",
"queries"  : [ {
    "name" : "Invoice",
    "convertToCurrencies": "GBP,JPY",
    "query" : "Select amount, createddate from invoice",
    "type" : "zoqlexport"
  }]
}

Example data source export file

The above example SOAP API and AQuA API requests generate a data source export file with the following currency conversion fields added:

• Invoice.AmountGBP

• Invoice.AmountCurrencyRoundingBGP

• Invoice.ExchangeRateGBP

• Invoice.AmountJPY

• Invoice.AmountCurrencyRoundingJPY

• Invoice.ExchangeRateJPY

• Invoice.ExchangeRateDate

• Invoice.ProviderExchangeRateDate

• Invoice.TransactionCurrency

Convert amounts into my home currency and other currencies in the same export file

You can include conversion fields for your home currency and for any other specified currencies in the same data source export. In this scenario, the following fields appear only once and apply to both the home currency and the other currencies:

• <Object>.ExchangeRateDate

• <Object>.ProviderExchangeRateDate

• <Object>.TransactionCurrency