Currency

Each store sets its own currency, and every product and pricing response includes the currency it is expressed in — so displaying money is a matter of formatting the amount with the symbol that came back alongside it, without a separate currency call.

Where currency lives

Currency travels with the priced data, on every catalog and pricing response. This is the primary source for rendering a price:

Field	On	Meaning
`display_currency`	each product (`listProducts`, `getProduct`) and every pricing response	The currency code the price is in (e.g. `"USD"`).
`currency_symbol`	same	The symbol to render (e.g. `"$"`).
`base_currency`, `exchange_rate`	pricing responses (`getProductPrice`/`getProductPrices`)	The store’s base currency and the rate applied to reach `display_currency`.

Both display_currency and currency_symbol are selectable via sparse fieldsets — request just them with fields=...,display_currency,currency_symbol to keep a grid lean. So a storefront renders the right price and symbol straight from the catalog read it was already making — no extra round trip.

const { products } = await client.products.listProducts({
  fields: 'id,name,price,display_currency,currency_symbol',
});
// → products[0] === { id, name, price: 349.99, display_currency: 'USD', currency_symbol: '$' }

Store information lists what the store is configured for — it’s reference metadata, not the per-response source of truth. client.system.getStoreInfo (single store) / client.marketplace.getMarketplaceInfo (marketplace) return:

{
  "store": {
    "store_id": "ef7b07d3-…",
    "name": "Galactic Test Store",
    "default_currency": "USD",
    "currencies": ["USD", "GBP", "EUR"],
    "timezone": "America/New_York"
  },
  "features": { "multi_currency": true, "...": "..." }
}

Field	Meaning
`store.default_currency`	The store’s base currency (the same value the pricing endpoints return as `base_currency`).
`store.currencies`	Every currency the store has enabled.
`features.multi_currency`	Whether the store offers more than one currency to shoppers.

Use store info to know which currencies a store supports (e.g. to render a currency switcher); use the display_currency/currency_symbol on each priced response to actually render prices.

Single-currency store

{ "store": { "default_currency": "EUR", "currencies": ["EUR"] } }

// Format straight from each product — the currency rides along on every row.
const fmt = (amount: number, currency: string) =>
  new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(amount);

const { products } = await client.products.listProducts({
  fields: 'name,price,display_currency,currency_symbol',
});
products.forEach((p) => console.log(p.name, fmt(p.price, p.display_currency))); // e.g. €349.99

Multi-currency store

{
  "store": { "default_currency": "EUR", "currencies": ["EUR", "KES", "CNY", "GBP", "USD"] },
  "features": { "multi_currency": true }
}

Prices are returned in default_currency. When features.multi_currency is true, you can offer a currency switcher built from store.currencies and convert amounts for display.

const { store, features } = await client.system.getStoreInfo({ sections: 'features' });
const baseCurrency = store.default_currency; // 'EUR' — the currency prices are in
const options = store.currencies;            // ['EUR','KES','CNY','GBP','USD']
const offerSwitcher = features?.multi_currency === true;

Marketplace

On a marketplace deployment the storefront currency is marketplace-wide — it’s the operator’s single default, so the whole aggregated catalog renders in one currency (you do not get a different currency per merchant). Every product still carries display_currency/currency_symbol inline, so you format the same way; they just resolve to the marketplace’s currency across all merchants. client.marketplace.getMarketplaceInfo reports the marketplace’s default_currency, and getMarketplaceInfo({ storeId }) returns a single merchant’s store info. (Each merchant still sets its own prices; the operator sets the currency they’re shown in.)

If default_currency is ever absent for a store, fall back to the first entry of store.currencies.

Currency is validated server-side at payment

The currency a payment is charged in is decided by Galactic Core, not by the caller. When you initialize a payment, any currency you pass is treated as a request that is validated against the store’s enabled currencies — the same set store.currencies reports:

A currency the store supports is accepted (this is what a multi-currency storefront’s currency switcher relies on).
A currency the store does not support is rejected with 400 unsupported_currency, listing the currencies that are allowed — so a mismatched or unexpected currency can never be charged.
Omit currency and the store’s default is used.

{
  "error": {
    "code": "unsupported_currency",
    "message": "This store does not accept JPY. Supported: EUR, GBP, CNY, KES, USD.",
    "details": { "requested": "JPY", "supported": ["EUR", "GBP", "CNY", "KES", "USD"], "store_default": "EUR" }
  }
}

On a marketplace deployment this resolves to the operator’s single marketplace currency, and a checkout that requests a different currency is rejected the same way. In every case the amount and the currency the shopper is charged are the server’s decision, and the currency returned on the priced response being checked out is always in the accepted set.

Server-side validation makes a pre-check unnecessary. Reading store.currencies — or the display_currency on each priced response — is what lets a UI offer only currencies that will be accepted in the first place.

Introduction

How GC Works

Build with AI

Extend the platform

Commerce capabilities

Distribute

Native Integrations

Resources

Where currency lives

Single-currency store

Multi-currency store

Marketplace

Currency is validated server-side at payment

​Where currency lives

​Single-currency store

​Multi-currency store

​Marketplace

​Currency is validated server-side at payment

Where currency lives

Single-currency store

Multi-currency store

Marketplace

Currency is validated server-side at payment