Skip to main content
Currencies define the monetary units used across your store. Each zone is associated with a currency, and each price record is linked to a currency. Shopper supports multi-currency pricing out of the box, with over 150 currencies seeded during installation.

​
Model

The model used is Shopper\Core\Models\Currency. It implements Shopper\Core\Models\Contracts\Currency. The model has a global enabled scope that automatically filters out disabled currencies (see Pricing for details).

​
Database Schema

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
namestringno-Currency name (e.g., “US Dollar”)
codestring(10)no-ISO 4217 code (e.g., “USD”), unique
symbolstring(25)no-Currency symbol (e.g., ”$“)
formatstring(50)no-Display format pattern
exchange_ratedecimal(10,2)yesnullExchange rate relative to base currency
is_enabledbooleannotrueWhether the currency is active

​
How Currencies are Created

Currencies are defined in a JSON file at core/database/data/currencies.json. When you run php artisan shopper:install, a migration reads this file and inserts all currencies into the database. Shopper ships with over 150 currencies out of the box, so you rarely need to add more. If you do need a custom currency, create a migration that inserts it into the currencies table directly.

​
How Setup Store Currencies

After installing Shopper, you need to set up your store and during this step you’ll choose the currencies you want for your store and set the one that will be used by default. But once you’ve done this, in your general settings Settings > General, you can change these currencies.
Store currency

​
Zero-Decimal Currencies

Some currencies have no subdivision (no “cents”). For example, the Japanese Yen (JPY) and the Central African CFA Franc (XAF) are stored as whole numbers — 1000 JPY is 1000, not 10.00. Shopper handles this automatically. The is_no_division_currency() helper checks if a currency code is zero-decimal, and zero_decimal_currencies() returns the full list: 
is_no_division_currency('XAF'); // true
is_no_division_currency('USD'); // false

zero_decimal_currencies();
// ['BIF', 'CLP', 'DJF', 'GNF', 'HTG', 'JPY', 'KMF', 'KRW',
//  'MGA', 'PYG', 'RWF', 'VND', 'VUV', 'XAF', 'XAG', 'XAU',
//  'XDR', 'XOF', 'XPF']
The shopper_money_format() helper and the MoneyInput form component both use this to determine whether to divide/multiply by 100. See the Pricing documentation for details.

​
Relation to Other Entities

​
Store

A store has a default currency and can have many currencies. These currencies are then used in other relations, such as when associating a zone with a currency. These 2 values are available throw the Shopper\Core\Models\Setting Model, under the values default_currency_id and currencies for the key column. The shopper_setting('default_currency_id') helper will return the id of the default currency and shopper_setting('currencies') will return and array of currencies setup for your store

​
Zone

Each Zone is associated with a currency. A currency can be used in more than one zone, but a zone can have only one currency. The relation is available on a Zone throw the currency relation and will return a Shopper\Core\Models\Currency object. You can also access the currency code through the attribute currency_code on the zone.

​
Price

The Price entity is used to represent a price associated with an entity, for example for products or variants. Each price is associated with a currency. The relation is available on a Price throw the currency relation and will return a Shopper\Core\Models\Currency object. You can also access the currency code through the attribute currency_code on the zone.