unirate-vendure

UniRate API currency-exchange integration for Vendure — an injectable UniRateService (live rates, conversion, supported currencies, VAT rates) plus optional unirateConvert / unirateRate / unirateSupportedCurrencies GraphQL queries, with zero runtime dependencies.

---

Install

npm install unirate-vendure

@vendure/core (>=3.0.0), @nestjs/common, @nestjs/graphql, graphql, and reflect-metadata are peer dependencies — your Vendure project already provides them.

Get a free API key at unirateapi.com.

---

Quick start

1. Register the plugin in vendure-config.ts

import { VendureConfig } from "@vendure/core";
import { UniRatePlugin } from "unirate-vendure";

export const config: VendureConfig = {
  // ...your existing config
  plugins: [
    UniRatePlugin.init({
      apiKey: process.env.UNIRATE_API_KEY!,
      defaultBaseCurrency: "USD", // used by getRates() when no base is passed
      exposeShopApi: false,       // Admin API only by default
    }),
  ],
};

2. Inject UniRateService anywhere

UniRateService is a standard NestJS provider, exported by the plugin and available application-wide:

import { Injectable } from "@nestjs/common";
import { UniRateService } from "unirate-vendure";

@Injectable()
export class PricingService {
  constructor(private readonly unirate: UniRateService) {}

  async priceInEur(usd: number): Promise<number> {
    return this.unirate.convert(usd, "USD", "EUR");
  }
}

3. Or query the GraphQL API

The plugin extends the Admin API (and the Shop API when exposeShopApi: true) with:

query {
  unirateConvert(from: "USD", to: "EUR", amount: 100) {
    from
    to
    amount
    result
  }
  unirateRate(from: "USD", to: "GBP") {
    rate
  }
  unirateSupportedCurrencies
}

By default the queries are rejected on the Shop API to avoid exposing exchange lookups to unauthenticated storefront traffic. Set exposeShopApi: true to opt in.

---

UniRateService API

Method	Returns	Tier
getRate(from, to)	Promise<number>	Free
getRates(base?)	Promise<Record<string, number>>	Free
convert(amount, from, to)	Promise<number>	Free
getSupportedCurrencies()	Promise<string[]>	Free
getVatRates() / getVatRates(country)	Promise<VATRatesAll | VATRateOne>	Free
getHistoricalRate(date, from, to)	Promise<number>	Pro
getTimeSeries(startDate, endDate, base?, currencies?)	Promise<Record<string, Record<string, number>>>	Pro
getHistoricalLimits()	Promise<HistoricalLimitsResponse>	Pro
raw	UniRateClient	escape hatch

Currency and country codes are uppercased automatically before the request.

---

Plugin options

UniRatePlugin.init({
  apiKey: string;             // required — your UniRate API key
  baseUrl?: string;           // default "https://api.unirateapi.com"
  timeoutMs?: number;         // default 30000
  defaultBaseCurrency?: string; // default "USD"
  exposeShopApi?: boolean;    // default false (Admin API only)
});

---

Error handling

Every method rejects with a typed error inheriting from UniRateError:

HTTP	Error	When
400	InvalidRequestError	Bad parameters
401	AuthenticationError	Missing / invalid API key
403	ProRequiredError	Endpoint requires a Pro subscription
404	InvalidCurrencyError	Unknown currency / no data
429	RateLimitError	Rate limit exceeded
other / network	UniRateError	Carries status + body

import { ProRequiredError } from "unirate-vendure";

try {
  await unirate.getHistoricalRate("2020-01-01", "USD", "EUR");
} catch (err) {
  if (err instanceof ProRequiredError) {
    // historical data needs a UniRate Pro plan
  }
}

Historical and time-series endpoints are Pro-gated and return 403 (ProRequiredError) on the free tier.

---

Rate limits

The free tier is rate limited; a 429 surfaces as RateLimitError. Upgrade at unirateapi.com for higher limits and historical data.

---

Related UniRate integrations

• @unirate/nestjs — the NestJS module this plugin builds on
• medusa-plugin-unirate — the same integration for Medusa v2
• unirate-api — the standalone Node client

---

License

MIT © Unirate Team