Supplier Currency Onboarding Automation in 2026: Vendor Masters, ERP Exports, and FX Evidence

What the vendor-master record should keep

The supplier record should store more than a currency code. Keep the source fields and the API evidence together so a later AP issue can be traced without asking engineering to rebuild the onboarding run.

• Supplier ID, legal entity, country, and record owner
• Invoice currency and payment currency
• Currency name, symbol, decimal digits, and rounding
• Functional or reporting currency for first-rate checks
• Policy date, request timestamp, and returned rateTime
• Approval status, exception reason, and reviewer

API examples for supplier onboarding

Start with currency metadata. The public OpenAPI schema includes ISO code, display names, symbols, decimal digits, rounding, units, banknotes, coins, and countries or regions.

curl "https://api.currency-exchange.app/v1-list-currencies?code=MXN&active=true&expand=name&expand=symbol&expand=iso&expand=decimalDigits&expand=rounding&expand=countries" \
  -H "x-api-key: YOUR_API_KEY"

Then run a first conversion or pair-rate evidence check. Use a historical date only when the contract, PO, or finance policy calls for it.

curl "https://api.currency-exchange.app/v1-convert-currency?from=MXN&to=USD&amount=10000&date=2026-06-01" \
  -H "x-api-key: YOUR_API_KEY"

Review usage when imports, spreadsheet scripts, and agents start making repeated validation calls.

curl "https://api.currency-exchange.app/v1-get-api-usage?from=2026-06-01&to=2026-06-30&service=currency" \
  -H "x-api-key: YOUR_API_KEY"

A TypeScript worker can validate metadata and first-rate evidence before writing the result into the vendor master.

type SupplierCurrencyInput = {
  supplierId: string;
  invoiceCurrency: string;
  paymentCurrency: string;
  reportingCurrency: string;
  policyDate?: string;
};

type CurrencyMetadata = {
  code: string;
  name?: string;
  symbol?: string;
  decimalDigits?: number;
  rounding?: number;
  countries?: string[];
};

type CurrencyListPayload = {
  list: CurrencyMetadata[];
};

type ConversionEvidence = {
  exchangeRate: number;
  rateTime: string;
  originalAmount: number;
  convertedAmount: number;
};

type SupplierCurrencyEvidence = {
  supplierId: string;
  invoiceCurrency: CurrencyMetadata;
  paymentCurrency: CurrencyMetadata;
  firstRate: ConversionEvidence;
  status: 'approved' | 'needs-review';
  reasons: string[];
};

function isCurrencyMetadata(value: unknown): value is CurrencyMetadata {
  if (!value || typeof value !== 'object') return false;
  const record = value as Record<string, unknown>;

  return typeof record.code === 'string';
}

function isCurrencyListPayload(value: unknown): value is CurrencyListPayload {
  if (!value || typeof value !== 'object') return false;
  const record = value as Record<string, unknown>;

  return Array.isArray(record.list) && record.list.every(isCurrencyMetadata);
}

function isConversionEvidence(value: unknown): value is ConversionEvidence {
  if (!value || typeof value !== 'object') return false;
  const record = value as Record<string, unknown>;

  return (
    typeof record.exchangeRate === 'number' &&
    typeof record.rateTime === 'string' &&
    typeof record.originalAmount === 'number' &&
    typeof record.convertedAmount === 'number'
  );
}

async function getCurrencyMetadata(code: string): Promise<CurrencyMetadata> {
  const url = new URL('https://api.currency-exchange.app/v1-list-currencies');
  url.searchParams.set('code', code);
  url.searchParams.set('active', 'true');
  url.searchParams.append('expand', 'name');
  url.searchParams.append('expand', 'symbol');
  url.searchParams.append('expand', 'iso');
  url.searchParams.append('expand', 'decimalDigits');
  url.searchParams.append('expand', 'rounding');
  url.searchParams.append('expand', 'countries');

  const response = await fetch(url, {
    headers: { 'x-api-key': process.env.FX_API_KEY ?? '' },
  });
  const payload: unknown = await response.json();

  if (!isCurrencyListPayload(payload) || !payload.list[0]) {
    throw new Error('Unsupported supplier currency');
  }

  return payload.list[0];
}

async function getFirstRate(input: SupplierCurrencyInput): Promise<ConversionEvidence> {
  const url = new URL('https://api.currency-exchange.app/v1-convert-currency');
  url.searchParams.set('from', input.paymentCurrency);
  url.searchParams.set('to', input.reportingCurrency);
  url.searchParams.set('amount', '10000');

  if (input.policyDate) {
    url.searchParams.set('date', input.policyDate);
  }

  const response = await fetch(url, {
    headers: { 'x-api-key': process.env.FX_API_KEY ?? '' },
  });
  const payload: unknown = await response.json();

  if (!isConversionEvidence(payload)) {
    throw new Error('Unexpected conversion response shape');
  }

  return payload;
}

export async function validateSupplierCurrency(input: SupplierCurrencyInput): Promise<SupplierCurrencyEvidence> {
  const invoiceCurrency = await getCurrencyMetadata(input.invoiceCurrency);
  const paymentCurrency = await getCurrencyMetadata(input.paymentCurrency);
  const firstRate = await getFirstRate(input);
  const reasons: string[] = [];

  if (input.invoiceCurrency !== input.paymentCurrency) {
    reasons.push('Invoice currency differs from payment currency');
  }

  return {
    supplierId: input.supplierId,
    invoiceCurrency,
    paymentCurrency,
    firstRate,
    status: reasons.length > 0 ? 'needs-review' : 'approved',
    reasons,
  };
}

The evidence stored with the supplier can stay compact.

{
  "supplierId": "supplier_1042",
  "invoiceCurrency": {
    "code": "MXN",
    "name": "Mexican Peso",
    "symbol": "$",
    "decimalDigits": 2
  },
  "paymentCurrency": {
    "code": "MXN",
    "name": "Mexican Peso",
    "symbol": "$",
    "decimalDigits": 2
  },
  "firstRate": {
    "exchangeRate": 0.054,
    "rateTime": "2026-06-01T00:00:00.000Z",
    "originalAmount": 10000,
    "convertedAmount": 540
  },
  "status": "approved",
  "reasons": []
}

Internal links for the implementation path

• inspect the OpenAPI reference for currency, conversion, rate, key, and usage endpoints
• review the supported-currency list before choosing vendor-master defaults
• connect supplier currency checks to currency master-data controls
• carry validated supplier currencies into AP aging automation
• set governance rules for API keys, rate evidence, and workflow ownership

FAQ