> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laravelshopper.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Currencies

> Configure and manage multiple currencies for your global store

Currencies define the monetary units used across your store. Each [zone](/v2/zones) is associated with a currency, and each [price](/v2/pricing) 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](/v2/pricing#currency-model) for details).

### Database Schema

| Column          | Type          | Nullable | Default | Description                             |
| --------------- | ------------- | -------- | ------- | --------------------------------------- |
| `id`            | bigint        | no       | auto    | Primary key                             |
| `name`          | string        | no       | -       | Currency name (e.g., "US Dollar")       |
| `code`          | string(10)    | no       | -       | ISO 4217 code (e.g., "USD"), unique     |
| `symbol`        | string(25)    | no       | -       | Currency symbol (e.g., "\$")            |
| `format`        | string(50)    | no       | -       | Display format pattern                  |
| `exchange_rate` | decimal(10,2) | yes      | null    | Exchange rate relative to base currency |
| `is_enabled`    | boolean       | no       | true    | Whether 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](/v2/setup-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.

<Frame caption="Store currency">
  <img src="https://mintcdn.com/shopperlabs-ee054f5e/eVX_9bJEbNf6CmDO/images/v2/store-currency.png?fit=max&auto=format&n=eVX_9bJEbNf6CmDO&q=85&s=f5e2ddf1384cd9bd76f8b702d488ea6d" alt="Store currency" width="2628" height="506" data-path="images/v2/store-currency.png" />
</Frame>

## 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, so 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:

```php theme={null}
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](/v2/pricing) 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.