Zones

Zones define geographic regions for your store. Each zone groups countries together and associates them with a currency, carriers, payment methods, and tax rules. When a customer checks out, Shopper resolves their zone from the shipping address and uses it to determine available shipping options, payment methods, and tax rates.

Model

The model used is Shopper\Core\Models\Zone. It uses the HasSlug trait for automatic slug generation. The model is not configurable via config/shopper/models.php.

Database Schema

Column	Type	Nullable	Default	Description
`id`	bigint	no	auto	Primary key
`name`	string	no	-	Zone name (unique)
`slug`	string	yes	auto	URL-friendly identifier (unique)
`code`	string	yes	null	Short code identifier (unique)
`is_enabled`	boolean	no	false	Zone visibility
`currency_id`	bigint	yes	null	FK to currencies table
`metadata`	jsonb	yes	null	Additional custom data
`created_at`	timestamp	yes	null	Creation timestamp
`updated_at`	timestamp	yes	null	Last update timestamp

Pivot Table

The zone_has_relations pivot table connects zones to countries, carriers, payment methods, and collections through a polymorphic relationship.

Column	Type	Description
`zone_id`	bigint	FK to zone
`zonable_type`	string	Morph type (Country, Carrier, PaymentMethod, Collection)
`zonable_id`	bigint	FK to the related model

Relationships

Currency

Each zone is associated with one currency. This determines which currency is used for pricing and checkout in that zone.

$zone->currency;       // Currency model
$zone->currency_code;  // "EUR" (computed accessor)

Countries

Zones group multiple countries together. When a customer enters a shipping address, Shopper resolves the zone by matching the country.

$zone->countries;

$zone->countries()->attach([$franceId, $germanyId, $belgiumId]);

Carriers

Carriers (shipping providers) are scoped to zones. A carrier available in Europe may not be available in North America.

$zone->carriers;

$zone->carriers()->attach([$colissimoId, $dhlId]);

Payment Methods

Payment methods are scoped to zones. For example, iDEAL is only available in the Netherlands zone.

$zone->paymentMethods;

$zone->paymentMethods()->attach([$stripeId, $idealId]);

Shipping Options

Each zone has shipping options (carrier options with rates) available at checkout:

$zone->shippingOptions;

Collections

Collections can be scoped to specific zones for region-specific merchandising:

$zone->collections;

Query Scopes

The enabled scope filters zones that are active:

use Shopper\Core\Models\Zone;

Zone::query()->enabled()->get();

Computed Attributes

The Zone model provides computed attributes that return comma-separated names for related entities:

$zone->countries_name;  // "France, Germany, Belgium"
$zone->carriers_name;   // "Colissimo, DHL"
$zone->payments_name;   // "Stripe, iDEAL"
$zone->currency_code;   // "EUR"

HasZones Trait

Models that can be scoped to zones use the HasZones trait. This is already applied to PaymentMethod, Carrier, and Collection models.

use Shopper\Core\Models\Traits\HasZones;

$model->zones;
$model->zones()->attach([$zoneId1, $zoneId2]);

Creating Zones

To create a zone for the European market:

use Shopper\Core\Models\Zone;
use Shopper\Core\Models\Country;

$zone = Zone::query()->create([
    'name' => 'Europe',
    'code' => 'EU',
    'is_enabled' => true,
    'currency_id' => $eurCurrency->id,
]);

$countries = Country::query()
    ->whereIn('cca2', ['FR', 'DE', 'BE', 'NL', 'ES', 'IT'])
    ->pluck('id');

$zone->countries()->attach($countries);
$zone->carriers()->attach([$colissimoId, $dhlId]);
$zone->paymentMethods()->attach([$stripeId]);

Retrieving Zones

To find the zone for a customer’s shipping address:

$zone = Zone::query()
    ->enabled()
    ->whereHas('countries', fn ($q) => $q->where('id', $countryId))
    ->first();

To get all enabled zones with their currencies:

$zones = Zone::query()
    ->enabled()
    ->with('currency')
    ->get();

Components

The zone management components are part of the settings configuration. To customize:

php artisan shopper:component:publish setting

Zone-related components in config/shopper/components/setting.php:

use Shopper\Livewire;

return [
    'pages' => [
        'zones' => Livewire\Pages\Settings\Zones::class,
    ],
    'components' => [
        'settings.zones.detail' => Livewire\Components\Settings\Zones\Detail::class,
        'settings.zones.shipping-options' => Livewire\Components\Settings\Zones\ZoneShippingOptions::class,
    ],
];

Prologue

Getting Started

Catalog

Sales

Store Setup

System

Storefront

Releases

Model

Database Schema

Pivot Table

Relationships

Currency

Countries

Carriers

Payment Methods

Shipping Options

Collections

Query Scopes

Computed Attributes

HasZones Trait

Creating Zones

Retrieving Zones

Components

​Model

​Database Schema

​Pivot Table

​Relationships

​Currency

​Countries

​Carriers

​Payment Methods

​Shipping Options

​Collections

​Query Scopes

​Computed Attributes

​HasZones Trait

​Creating Zones

​Retrieving Zones

​Components

Model

Database Schema

Pivot Table

Relationships

Currency

Countries

Carriers

Payment Methods

Shipping Options

Collections

Query Scopes

Computed Attributes

HasZones Trait

Creating Zones

Retrieving Zones

Components