Pricing
Multi-currency pricing for products and variants with cents-based storage.
Shopper supports multi-currency pricing for products and product variants. Each priceable model can have one price per currency, stored in a shared prices table through a polymorphic relationship. Prices are stored in cents following the Stripe/Shopify standard.
Money Storage Standard
All monetary values are stored as integers in cents. $29.99 is stored as 2999 cents. For zero-decimal currencies (XAF, JPY, KRW), the value is stored as-is since the currency has no subdivision (15000 FCFA is stored as 15000).
$product->prices()->create(['amount' => 2999, 'currency_id' => $usdCurrency->id]);
$product->prices()->create(['amount' => 15000, 'currency_id' => $xafCurrency->id]);Display
Use shopper_money_format() to convert cents to a human-readable format. The helper divides by 100 for standard currencies and passes zero-decimal currencies through unchanged. It uses Laravel's Number::currency() with the application locale, so the output follows app()->getLocale(). When you omit the currency, it uses the store's default currency from shopper_currency().
shopper_money_format(2999, 'USD'); // "$29.99"
shopper_money_format(15000, 'XAF'); // "FCFA 15,000" with the "en" locale, "15 000 FCFA" with "fr"
shopper_money_format(2999); // Formatted in the store's default currencyDefault Currency
The shopper_currency() helper returns the store's default currency code. It reads the default_currency_id setting, looks up the currency code, caches it for one hour, and falls back to 'USD' if no default is configured or the default currency is disabled. Saving the default currency in the admin settings clears this cache.
shopper_currency(); // "USD"Zero-Decimal Currencies
These helpers let you check whether a currency uses decimal subdivisions. The list holds BIF, CLP, DJF, GNF, HTG, JPY, KMF, KRW, MGA, PYG, RWF, VND, VUV, XAF, XAG, XAU, XDR, XOF and XPF. Every other currency is divided by 100.
zero_decimal_currencies(); // ['BIF', 'CLP', 'DJF', 'GNF', 'HTG', 'JPY', ...]
is_no_division_currency('XAF'); // true
is_no_division_currency('USD'); // falsePrice Model
The model used is Shopper\Core\Models\Price. It implements Shopper\Core\Models\Contracts\Price and is not configurable via config/shopper/models.php.
Database Schema
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
priceable_type | string | no | - | Morph alias: product or variant |
priceable_id | bigint | no | - | Foreign key to the priceable model |
amount | integer (unsigned) | yes | null | Selling price in cents, indexed |
compare_amount | integer (unsigned) | yes | null | Original/compare-at price in cents, for strikethrough display |
cost_amount | integer (unsigned) | yes | null | Cost price in cents, for margin and profit tracking |
currency_id | bigint | no | - | Foreign key to currencies table. Deleting a currency deletes its prices |
created_at | timestamp | yes | null | Creation timestamp |
updated_at | timestamp | yes | null | Last update timestamp |
Price Fields
Each price record has three amount fields that serve distinct business purposes:
| Field | What it represents | Shown to customers | Example |
|---|---|---|---|
amount | The current selling price | Yes | 1999 cents = $19.99 |
compare_amount | The original price before a sale or discount. Displayed as a strikethrough next to the selling price (what Shopify calls "compare at price") | Yes (as strikethrough) | 2999 cents = $29.99 |
cost_amount | What you paid your supplier. Used to calculate profit margins. Never displayed on the storefront | No | 850 cents = $8.50 |
For a product on sale, you would set all three: cost at 850, selling at 1999, and compare-at at 2999. The storefront shows "$19.99 $29.99" and you know the margin is $11.49.
Relationships
The priceable relationship connects a price to its parent model (Product or ProductVariant):
$price->priceable; // Returns the Product or ProductVariantThe currency relationship returns the currency for this price:
$price->currency; // Currency model
$price->currency_code; // "USD" (computed accessor)Price Helper
The Price model provides three methods that return a Shopper\Core\Helpers\Price value object with both the raw amount and a pre-formatted string. Each method returns null when its field is null or 0:
$priceHelper = $price->amountPrice();
$priceHelper->amount; // 2999
$priceHelper->formatted; // "$29.99"
$priceHelper->currency; // "USD"
$price->compareAmountPrice(); // Same pattern for compare_amount
$price->costAmountPrice(); // Same pattern for cost_amountThese three methods format the amount in the store's default currency (shopper_currency()), not in the currency of the price record. For a price in another currency, create the helper yourself with the record's currency code.
You can also create a Price helper directly. Pass the amount in cents as an integer:
use Shopper\Core\Helpers\Price as PriceHelper;
$helper = PriceHelper::from(2999, 'USD');
$helper->formatted; // "$29.99"
PriceHelper::from($price->amount, $price->currency_code)->formatted; // "€27.99" for a EUR priceHasPrices Trait
The Shopper\Core\Models\Traits\HasPrices trait is used by Product and ProductVariant to provide pricing capabilities. Any model implementing the Shopper\Core\Contracts\Priceable interface can use this trait.
To get the price for the store's default currency (shopper_currency()):
$price = $product->getPrice(); // ?Price modelTo get the price for a specific currency:
$price = $product->getPrice('EUR'); // ?Price modelThe method checks if the prices relationship is already loaded to avoid extra queries. When eager-loaded, it filters the collection in memory instead of hitting the database, and loads each price's currency only if it is missing.
To access all prices:
$product->prices; // Collection of Price modelsDeleting a product or a variant deletes its prices. For products this also happens on a soft delete.
Currency Model
The model used is Shopper\Core\Models\Currency. It implements Shopper\Core\Models\Contracts\Currency and has no timestamps.
Currency 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. Stored for reference only: Shopper never converts prices with it, so each currency needs its own price |
is_enabled | boolean | no | true | Whether the currency is active |
Enabled Scope
The Currency model has a global enabled scope that automatically filters out disabled currencies. All queries return only enabled currencies by default.
use Shopper\Core\Models\Currency;
Currency::query()->get(); // Only enabled currencies
Currency::query()->withoutGlobalScopes()->get(); // All currencies, including disabledZone Relationship
Each zone sells in one currency. The zone relationship returns a zone that uses this currency:
$currency->zone; // ?Zone modelSeveral zones can share one currency, and zone returns only one of them. To get every zone that uses a currency, query the zones directly:
use Shopper\Core\Models\Zone;
Zone::query()->where('currency_id', $currency->id)->get();Creating Prices
To set a price on a product or variant, create a Price record through the prices() relationship:
use Shopper\Models\Product;
$product = Product::query()->find($id);
$product->prices()->create([
'amount' => 2999,
'compare_amount' => 3999,
'cost_amount' => 850,
'currency_id' => $currencyId,
]);The prices table has no unique index on the model and currency pair. Calling create() twice for the same currency adds a second row, and getPrice() returns only one of them. To change an existing price, use updateOrCreate() or the SavePricingAction below.
Multi-Currency Pricing
To set prices in multiple currencies at once, use the SavePricingAction. It accepts an array keyed by currency ID and creates or updates prices in a single pass:
use Shopper\Actions\Store\Product\SavePricingAction;
$pricing = [
$usdCurrencyId => [
'amount' => 2999,
'compare_amount' => 3999,
'cost_amount' => 850,
],
$eurCurrencyId => [
'amount' => 2799,
'compare_amount' => 3799,
'cost_amount' => 800,
],
];
app()->call(SavePricingAction::class, [
'pricing' => $pricing,
'model' => $product,
]);The action uses updateOrCreate on each entry, so existing prices for a currency are updated rather than duplicated. An entry without an amount (or with 0) is skipped, and the action never deletes a price: a currency missing from the array keeps its current price.
Retrieving Prices
To get a product's price for the default currency and format it for display:
$price = $product->getPrice();
if ($price) {
shopper_money_format($price->amount, $price->currency_code);
}To display a sale price with strikethrough:
$price = $product->getPrice();
if ($price && $price->compare_amount) {
$selling = shopper_money_format($price->amount, $price->currency_code);
$original = shopper_money_format($price->compare_amount, $price->currency_code);
// Display: "$19.99" with "$29.99" crossed out
}To eager-load prices and avoid N+1 queries when listing products:
$products = Product::query()
->publish()
->with('prices.currency')
->get();
foreach ($products as $product) {
$price = $product->getPrice(); // No extra query, filtered from loaded relation
}Admin Components
MoneyInput
For Filament forms, use the MoneyInput component instead of TextInput for monetary fields. It handles conversion between human values (form) and cents (database) automatically:
use Shopper\Components\Form\MoneyInput;
MoneyInput::make('amount')
->currency('USD')
->suffix('USD');For zero-decimal currencies, the component adjusts the mask precision to 0 automatically. If no currency is specified, MoneyInput defaults to the store's configured currency via shopper_currency().
Table Columns
Use the ->currency() macro on Filament TextColumn for displaying monetary values:
use Filament\Tables\Columns\TextColumn;
TextColumn::make('amount')
->currency(fn ($record) => $record->currency_code)This macro uses shopper_money_format() internally. Without an argument, it formats in the store's default currency, and an empty value stays empty.
Publishing Components
To replace the pricing Livewire components with your own classes, publish the product components config:
php artisan shopper:component:publish productThis creates config/shopper/components/product.php, where the pricing components are registered. Point a key to your own class to replace it:
use Shopper\Livewire;
use Shopper\Livewire\Components;
return [
'components' => [
'products.pricing' => Components\Products\Pricing::class,
'slide-overs.manage-pricing' => Livewire\SlideOvers\ManagePricing::class,
],
];Last updated on
Edit on GitHub