FAQ – Using the Global Apex API to Apply Dated Exchange Rates on Records

Overview

Axy7 Currency Updater provides a global Apex API that allows customers and integrators to programmatically apply Dated Exchange Rates (DER) to Salesforce records.

This API is designed for advanced use cases where:

  • Records already exist in Salesforce

  • Exchange rates must be recalculated outside of triggers

  • Custom automation, batch jobs, integrations, or flows are required

The API reuses the same core logic used by:

  • Trigger-based updates

  • Scheduled nightly batches

  • Custom Date Exchange Rules

This ensures consistent, accurate, and Salesforce-native behavior.

What problem does this API solve?

In standard Salesforce behavior:

  • Exchange rates are applied automatically only in limited scenarios

  • Existing records are not recalculated unless updated

  • Triggers may not fire (data loads, integrations, special processes)

This API allows you to:

  • Initialize exchange rates on old records

  • Recalculate exchange rates after:

    • Enabling Advanced Currency Management (ACM)

    • Changing corporate currency

    • Fixing historical currency data

  • Apply exchange rates in custom automation (Flow, Batch, REST, LWC)

Global API Method

Method Signature

s4g_currencies.CurrencyUpdaterAPI.applyDatedExchangeRate(
List records,
String dateFieldApiName,
String targetFieldApiName
);

Parameters

Parameter Type Description
records List Records to update (must be queried and writable)
dateFieldApiName String API name of the date field driving the exchange rate
targetFieldApiName String API name of the field that stores the DER value

Important Notes

  • The method does not perform DML

  • The caller is responsible for calling update records

  • The method is bulk-safe

  • Works with any standard or custom object that:

    • Has CurrencyIsoCode

    • Has a date field

    • Has a numeric DER field

Feature Requirement – Apex API must be enabled

⚠️ Required Feature Parameter

This API requires the Apex API feature to be enabled in your org.

If the feature is not enabled, the method will throw an exception similar to:

Feature ApexAPI is disabled. Please contact Axy7 support.

How to enable it

  • The Apex API feature is edition-dependent

  • Please contact Axy7 Support to confirm availability and enablement

  • In most cases, this is included in Professional Edition or higher

📩 Contact support via AppExchange or your existing support channel.

How the API works internally

When you call the API:

  1. The method delegates to the internal CustomDatedExchangeHandler

  2. Exchange rates are resolved from Salesforce DatedConversionRate

  3. The logic:

    • Assigns 1.0 for corporate currency

    • Assigns 0 or null when the date is missing

    • Matches the correct rate using StartDate / NextStartDate

  4. The calculated value is set on the target field

  5. No DML is executed (caller controls persistence)

This is the same logic used by:

  • Triggers

  • Scheduled batches

  • Manual initialization utilities

Common Use Cases

1️⃣ Initializing exchange rates for old records

Scenario

  • Advanced Currency Management was enabled recently

  • Existing Opportunities have no dated exchange rate

  • You want to initialize historical values

Example

List records = [
SELECT Id, CurrencyIsoCode, CloseDate, Dated_Exchange_Rate__c
FROM Opportunity
WHERE Dated_Exchange_Rate__c = null
];s4g_currencies.CurrencyUpdaterAPI.applyDatedExchangeRate(
records,
'CloseDate',
'Dated_Exchange_Rate__c'
);update records;

✔ Safely initializes all historical records
✔ Uses the correct rate for each Close Date

2️⃣ Replacing existing (incorrect) exchange rates

Scenario

  • Exchange rates were calculated incorrectly in the past

  • Corporate currency or rate source changed

  • You want to recalculate everything

Example

List records = [
SELECT Id, CurrencyIsoCode, Invoice_Date__c, Invoice_DER__c
FROM Invoice__c
];s4g_currencies.CurrencyUpdaterAPI.applyDatedExchangeRate(
records,
'Invoice_Date__c',
'Invoice_DER__c'
);update records;

✔ Existing values are overwritten
✔ No dependency on triggers
✔ Safe for batch execution

3️⃣ Using the API from a Batch or Scheduled Job

Scenario

  • You want a custom scheduled recalculation

  • You need fine-grained control over which records are processed

Pattern

public void execute(Database.BatchableContext bc, List scope)

✔ Fully bulk-safe
✔ No trigger recursion
✔ Clean separation of logic

4️⃣ Using the API from Flow (via Invocable wrapper)

Scenario

  • Admins want to trigger recalculation from Flow

  • No Apex logic in Flow itself

Approach

  • Create a small Invocable Apex wrapper

  • Delegate to the global API

This keeps Flows simple and declarative.

What this API does NOT do

To keep behavior predictable and safe, the API:

❌ Does not perform DML
❌ Does not bypass Field-Level Security
❌ Does not create or modify Custom Date Exchange Rules
❌ Does not call external services
❌ Does not depend on trigger context

Error Handling & Best Practices

Best Practices

  • Always re-query records before passing them to the API

  • Always call update records after applying the rates

  • Process records in batches if volume is large

  • Validate that DatedConversionRate exists for the date range

Common reasons for empty values

Cause Resolution
No dated rates exist Load historical rates
Date field is null Ensure date is populated
Currency inactive Activate currency
Feature not enabled Contact Axy7 support

Frequently Asked Questions

Q: Does this work without Advanced Currency Management?

No. Dated exchange rates require Advanced Currency Management.

Q: Can I use this for standard and custom objects?

Yes. The API works with any object that:

  • Supports multi-currency

  • Has a date field

  • Has a numeric DER field

Q: Is this safe for production?

Yes. The API:

  • Is bulk-safe

  • Is trigger-safe

  • Uses Salesforce-native objects

  • Is already used internally by the package

Q: Why doesn't the API do the update itself?

This is intentional:

  • Gives callers full transaction control

  • Allows validation, logging, rollback strategies

  • Matches Salesforce ISV best practices

Summary

The applyDatedExchangeRate global API gives you:

✅ Full control over historical and custom recalculation
✅ Consistent logic with triggers and batches
✅ Safe, bulk-ready, ISV-grade behavior
✅ Flexibility for advanced automation scenarios

If you are unsure whether this feature is enabled in your org, or need help designing your automation, please contact the Axy7 support team — we're happy to help.

If you want, next I can:

  • Turn this into Markdown / HTML

  • Create a short AppExchange version

  • Add a Flow-only FAQ

  • Or write a "Migration to ACM" guide