Skip to main content

Scenario: Run foreign currency revaluation

Goal. At period end, your close tool or scheduler revalues the foreign-currency balances of a legal entity at the exchange rate of a date: the open customer transactions, the open vendor transactions and the general ledger balances. Lattice runs the same standard revaluation the D365 pages run, posts the unrealized exchange adjustments, and tells you whether anything was posted and in which voucher.

When to use. Month-end and year-end close, run from outside D365 or on a schedule. Run the three revaluations as separate requests, in the order your close checklist needs. Entries that are not exchange adjustments go through General and intercompany journals.

Prerequisites​

  1. Security. All three operations need privilege MGCLatticeGeneralLedgerServiceMaintain, in duty MGCLatticeIntegrationServiceOperationsDuty (integration operator and administrator roles). Without it D365 refuses the call with HTTP 403.
  2. D365 setup in the legal entity.
    • Exchange rates for the revaluation date in the ledger's exchange rate type (General ledger > Currencies > Currency exchange rates). USMF's Default type has open-ended USD to EUR and USD to CAD rates.
    • Unrealized gain and loss accounts: for customers and vendors on General ledger > Currencies > Currency revaluation accounts; for the ledger on General ledger > Ledger setup > Ledger (Accounts for currency revaluation). USMF's ledger uses 801600 Currency Adjustment Profits - Unrealized.
    • The main accounts you revalue are set up for foreign currency revaluation, and the posting period of the revaluation date is open.
  3. Lattice. A valid license (a never-registered environment is allowed through; an adverse verdict refuses the run with LicenseNotValid). The revaluation request takes no external keys and needs no Lattice parameters.

Steps​

The three operations are on MGCLatticeCurrencyRevaluationService in service group MGCLatticeGeneralLedgerServiceGroup and share one request contract. Send a POST with an OAuth 2.0 bearer token and the request in _request (see Trial and day-one guide).

  1. Revalue customer transactions. runCustomerRevaluation revalues the open customer transactions at the exchange rate of RevaluationDate (default: today in the calling user's time zone), for CurrencyCode or, when you leave it out, for every foreign currency. It uses the standard method, with the revaluation date as both the considered date and the date of the rate.

    POST https://<your-environment>/api/services/MGCLatticeGeneralLedgerServiceGroup/MGCLatticeCurrencyRevaluationService/runCustomerRevaluation
    {
      "_request": {
        "RequestId": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
        "LegalEntityId": "USMF",
        "UserContext": "close-tool",
        "RevaluationDate": "2026-10-31",
        "CurrencyCode": "EUR"
      }
    }

    The customer and vendor runs have no period and no account range: do not send FromDate, MainAccountFromId or MainAccountToId, which are refused.

  2. Revalue vendor transactions. Send the same request, with a new RequestId, to runVendorRevaluation:

    POST https://<your-environment>/api/services/MGCLatticeGeneralLedgerServiceGroup/MGCLatticeCurrencyRevaluationService/runVendorRevaluation

  3. Revalue the ledger. runLedgerRevaluation revalues the general ledger for CurrencyCode (or, when you leave it out, every currency posted to the ledger in the period), from FromDate through RevaluationDate, optionally only for main accounts MainAccountFromId through MainAccountToId. FromDate defaults to the start of the fiscal year of RevaluationDate; both dates must be in one fiscal year.

    POST https://<your-environment>/api/services/MGCLatticeGeneralLedgerServiceGroup/MGCLatticeCurrencyRevaluationService/runLedgerRevaluation
    {
      "_request": {
        "RequestId": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c",
        "LegalEntityId": "USMF",
        "UserContext": "close-tool",
        "RevaluationDate": "2026-10-31",
        "CurrencyCode": "EUR",
        "MainAccountFromId": "110110",
        "MainAccountToId": "801600"
      }
    }

  4. Read the result. Every successful run answers Success true and Status 3; what it posted is in DocumentId, PostedDocumentId and the message:

    OutcomeDocumentId / PostedDocumentIdMessage
    Customer or vendor adjustments postedThe adjustment voucher"Customer (Vendor) foreign currency revaluation as of ... adjusted N transaction(s) in voucher ..."
    Customer or vendor: nothing to adjustEmpty"... found nothing to adjust. Nothing was posted."
    Ledger adjustments postedThe adjustment voucher"Ledger foreign currency revaluation for EUR from ... through ... was posted in voucher ..."
    Ledger: nothing to adjustEmpty"Ledger foreign currency revaluation for ... found nothing to adjust. Nothing was posted."
    Ledger, no currency sent, no transactions in the periodEmpty"No ledger transactions were posted in any currency between ... and ..., so there is nothing to revalue."

    An empty DocumentId on a successful run is a normal result, not an error: there was nothing to revalue at that rate. Use DocumentId (not the message text, which is localized) to decide whether a voucher was posted.

Bulk variants runCustomerRevaluationBatch, runVendorRevaluationBatch and runLedgerRevaluationBatch take a _requests list, for example one item per legal entity. Large runs can be queued with submitAsyncOperation and polled with getAsyncOperationStatus (see API reference, sections 19 and 21).

How to verify​

  • The response: Success true, Status 3, and, when adjustments were posted, DocumentId = PostedDocumentId = the voucher.
  • The customer adjustments: read LatticeCustomerTransactions filtered on Voucher (the returned voucher) and dataAreaId, with cross-company=true; the rows have TransactionType ExchAdjustment. For vendors, read LatticeVendorTransactions the same way.
  • The ledger side of any run: LatticeGeneralLedgerEntries with $filter=SubledgerVoucher eq '<voucher>' and LegalEntityId eq 'USMF'.
  • In D365: General ledger > Inquiries and reports > Voucher transactions for the voucher; the revaluation history on General ledger > Currencies > Foreign currency revaluation (ledger) and on the Foreign currency revaluation pages under Accounts receivable > Periodic tasks and Accounts payable > Periodic tasks.
  • The call: System administration > Inquiries > Lattice > Services > Service call log, or LatticeServiceCallLogs filtered on your RequestId.

When it goes wrong​

A failed run answers Success false, Status 4, an ErrorCode and a generic Message; the reasons are in Errors.

ErrorCodeTypical cause (text in Errors)What to do
ValidationFailed (1)No RequestId or unknown LegalEntityId; "FromDate, MainAccountFromId and MainAccountToId apply to runLedgerRevaluation only. ... does not accept them."; a ledger FromDate after RevaluationDate; "The ledger revaluation settings are not valid; see the errors for the reason." (for example dates in two fiscal years)Correct the request and resend.
BusinessRule (4)The standard revaluation stopped: no exchange rate for the date, no revaluation accounts, a closed periodFix the setup named in Errors, then resend.
PreviewUnsupported (10)PreviewMode true: revaluation has no previewSend without PreviewMode. Nothing was run.
TransientRuntime (6)Infrastructure fault; IsRetryable trueResend with the same RequestId.
DuplicateRequest (7)The RequestId was first used for another operation (for example the customer run's id sent to the vendor run)Send a new RequestId for each run.
LicenseNotValid (12)The license verdict is adverse; IsRetryable trueRenew the license, then resend.

Choosing the RequestId. A revaluation is a run, not a document: resending a RequestId that succeeded returns the first result and does not run again, while a new RequestId runs a new revaluation. Give each run (legal entity, operation, revaluation date) its own stable RequestId, and reuse it only when you retry that same run. A failed run releases its RequestId, so you can resend it after fixing the cause.

Queued runs. A run submitted with submitAsyncOperation that fails while it runs lands in the dead-letter queue (System administration > Inquiries > Lattice > Integration operations > Integration operations console); see Integration operations.

Reference​