payload plugin unirate

payload-plugin-unirate

A Payload CMS v3 plugin that integrates the UniRate API for currency exchange rates and VAT data. It appends four server-side endpoints under /api/unirate and ships an optional prefilled currency select field — your API key stays server-side, never exposed to clients. Zero runtime dependencies (payload is a peer).

Install

npm install payload-plugin-unirate

Requires Payload >=3.0.0 (peer dependency) and Node >=18.20.

Quick start

// payload.config.ts
import { buildConfig } from "payload";
import { uniratePlugin } from "payload-plugin-unirate";

export default buildConfig({
  // ...your usual config
  plugins: [
    uniratePlugin({
      apiKey: process.env.UNIRATE_API_KEY, // or omit and set the env var
    }),
  ],
});

Set your key (recommended over inlining it):

UNIRATE_API_KEY=your_key_here

Options

uniratePlugin(options):

Option	Type	Default	Description
apiKey	string	process.env.UNIRATE_API_KEY	UniRate API key (stays server-side).
baseUrl	string	https://api.unirateapi.com	API base URL.
disabled	boolean	false	When true, the plugin is a no-op and adds no endpoints.
timeoutMs	number	30000	Per-request timeout.

Endpoints

The plugin appends these custom endpoints (Payload serves custom endpoints under the /api prefix):

Method	Path	Description
GET	/api/unirate/rate?from=USD&to=EUR	Exchange rate (single, or all rates for a base when to is omitted)
GET	/api/unirate/convert?from=USD&to=EUR&amount=100	Convert an amount
GET	/api/unirate/currencies	List supported currencies
GET	/api/unirate/vat?country=DE	VAT rates (optional country filter)

Example:

curl "http://localhost:3000/api/unirate/convert?from=USD&to=EUR&amount=100"
# → { "from": "USD", "to": "EUR", "amount": 100, "result": 92.00 }

When no API key is configured, the endpoints respond 503 (and log a warning) rather than crashing at boot.

Currency select field

An exported helper builds a Payload select field prefilled with common ISO-4217 currency codes:

import { currencyField } from "payload-plugin-unirate";

const Products = {
  slug: "products",
  fields: [
    { name: "title", type: "text" },
    currencyField({ name: "priceCurrency", defaultValue: "USD", required: true }),
  ],
};

Pass options: ["USD", "EUR", ...] to override the code list, or fetch the live list from /api/unirate/currencies.

Error handling

Endpoint responses map upstream UniRate errors to the appropriate HTTP status:

Status	Meaning
400	Invalid request parameters
401	Missing or invalid API key
403	Endpoint requires a Pro subscription
404	Currency not found / no data
429	Rate limit exceeded
503	Service unavailable / plugin not configured
502	Upstream/transport failure

The internal client and its typed error classes are also exported for direct use in hooks or custom endpoints:

import { UniRateClient, AuthenticationError, RateLimitError, ProRequiredError } from "payload-plugin-unirate";

const client = new UniRateClient({ apiKey: process.env.UNIRATE_API_KEY! });
try {
  const rate = await client.getRate("USD", "EUR"); // → 0.92
} catch (err) {
  if (err instanceof AuthenticationError) { /* invalid key */ }
  if (err instanceof RateLimitError)      { /* slow down */   }
  if (err instanceof ProRequiredError)    { /* upgrade plan */ }
}

Free vs Pro tier

Free-tier endpoints: rates, convert, currencies, VAT rates. Historical data and time series require a Pro subscription.

Related packages

UniRate API client libraries: Python · Node.js · Go · Rust · Ruby · PHP · Java · Swift · .NET

Framework integrations: Next.js · Nuxt · SvelteKit · Astro · NestJS · Eleventy · React · Vue · tRPC

CMS & e-commerce: WordPress · Directus · Strapi · Payload (this package) · Medusa · Hugo · Jekyll

Data & AI: LangChain Python · LangChain.js · FastAPI · Flask · Django REST · dbt · Airflow

Other: MCP server · CLI · Obsidian · money gem · laravel-money

License

MIT © Unirate Team