multi-currency-and-advanced-currency-management

# Multi Currency And Advanced Currency Management

Use this skill when currency is no longer just a formatting concern. Multi-currency and Advanced Currency Management change how data is stored, queried, reported, and explained to the business. The most important design rule is to respect currency context instead of smuggling in hardcoded assumptions about one corporate currency.

---

## Before Starting

Gather this context before working on anything in this domain:

- Is multi-currency already enabled, and if not, has the team understood that activation is irreversible?
- Does the requirement involve Opportunity reporting, forecasting, rollups, or Apex calculations that depend on exchange rates?
- Does the consumer need the stored transaction currency, the user's currency, or dated historical conversion?

---

## Core Concepts

### Activation Changes The Data Model

Once multi-currency is enabled, currency context becomes part of the record model through `CurrencyIsoCode` and exchange-rate behavior. Teams should stop assuming every `Amount` field is implicitly the same currency everywhere.

### `CurrencyIsoCode` Is Not Optional Context

When Apex or integrations move money-like values around, the ISO code matters. A number without its currency context is usually incomplete business data.

### `convertCurrency()` Serves A Different Need

`convertCurrency()` is for returning values converted into the running user's currency context in SOQL. It is different from preserving the stored transactional currency and should be chosen intentionally.

### Advanced Currency Management Adds Time Dimension

ACM uses dated exchange rates for supported use cases such as opportunity reporting. That improves historical correctness, but it also changes reporting and summary expectations. Designs that ignore the time dimension eventually confuse finance and sales users.

---

## Common Patterns

### Currency-Aware Query Pattern

**When to use:** Apex or reporting logic must display both amount and currency context clearly.

**How it works:** Query `CurrencyIsoCode` with the amount fields you expose and use `convertCurrency()` only when the user-currency projection is the actual requirement.

**Why not the alternative:** Returning bare amounts encourages silent conversion mistakes downstream.

### Historical Reporting With ACM

**When to use:** The business needs dated exchange-rate behavior for historical opportunity analysis.

**How it works:** Enable ACM deliberately and document which reports and summaries change meaning under dated rates.

### Integration DTO With Currency Context

**When to use:** Money values leave Salesforce through Apex or integration payloads.

**How it works:** Include both the amount and the ISO code rather than sending a bare decimal.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Org needs multiple transactional currencies | Multi-currency | Core platform support for currency context |
| Historical opportunity reporting needs dated conversion | ACM | Adds time-aware exchange-rate behavior |
| Apex exposes money values externally | Include `CurrencyIsoCode` with amount | Prevents silent interpretation errors |
| User-facing query wants viewer-currency projection | `convertCurrency()` | Returns user-context converted values |

---


## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] Activation and irreversibility implications are understood.
- [ ] Apex and integrations preserve currency context, not just numeric values.
- [ ] `CurrencyIsoCode` is queried or propagated where needed.
- [ ] `convertCurrency()` is used only when user-currency projection is intended.
- [ ] ACM implications for reporting, rollups, and finance users are documented.
- [ ] Hardcoded single-currency assumptions are challenged.

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Multi-currency activation is irreversible** - teams must treat it as an architectural decision, not a casual setting toggle.
2. **Amounts without ISO context are misleading** - Apex and integrations often lose meaning when they move only decimals.
3. **`convertCurrency()` is not the same as preserving stored currency** - it serves a different consumer need.
4. **ACM changes historical reporting expectations** - the business must understand why values differ over time.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| Currency design review | Findings on activation, conversion, reporting, and Apex handling |
| Query guidance | Pattern for stored-currency versus converted-currency retrieval |
| ACM decision | Recommendation for when dated exchange rates are justified |

---

## Related Skills

- `data/roll-up-summary-alternatives` - use when parent totals and rollups become the main implementation issue.
- `apex/custom-metadata-in-apex` - use when exchange-rate or currency-routing config belongs in metadata-driven logic.
- `integration/oauth-flows-and-connected-apps` - use when the main blocker is external finance-system authentication rather than currency semantics.