Channels
Complete reference for the Channel model, sales channels, and multi-channel management in Shopper.
Channels represent different sales platforms where your products can be sold. Examples include your main website, mobile app, marketplace integrations, or physical stores.
Model
The model used is Shopper\Core\Models\Channel. It implements Shopper\Core\Models\Contracts\Channel and uses the HasSlug trait: the slug you set is converted with Str::slug() and gets a -1, -2 suffix when it is already taken. The slug is not generated from the name, so pass one when you create a channel. The model is configurable via config/shopper/models.php.
Extending the Model
To add custom behavior, extend the model and update your configuration:
namespace App\Models;
use Shopper\Core\Models\Channel as BaseChannel;
class Channel extends BaseChannel
{
}Update config/shopper/models.php:
return [
'channel' => \App\Models\Channel::class,
];Database Schema
Channels are stored in the sh_channels table (sh_ is the default table prefix).
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
name | string | no | - | Channel name |
slug | string | yes | null | URL-friendly identifier (unique) |
description | text | yes | null | Channel description |
timezone | string | yes | null | Channel timezone, stored for your own code (Shopper does not read it) |
url | string | yes | null | Channel URL |
is_default | boolean | no | false | Default channel flag |
is_enabled | boolean | no | false | Whether the channel is active. Only enabled channels are listed in the admin product form |
metadata | jsonb | yes | null | Additional custom data, cast to an array |
created_at | timestamp | yes | null | Creation timestamp |
updated_at | timestamp | yes | null | Last update timestamp |
Relationships
Products
Channels have a many-to-many polymorphic relationship with products:
// Get all products for a channel
$channel->products; // Collection of Product models
// Add products to channel
$channel->products()->attach([$productId1, $productId2]);
// Remove products from channel
$channel->products()->detach($productId);
// Sync products
$channel->products()->sync($productIds);Orders and Carts
Orders and carts store the channel they were placed on in a nullable channel_id column and expose a channel() relation. Deleting a channel sets this column to null. The Channel model has no inverse relation, so query orders by the column:
use Shopper\Core\Models\Order;
$order->channel; // Channel model or null
$mobileOrders = Order::query()
->where('channel_id', $mobileChannel->id)
->count();Query Scopes
use Shopper\Core\Models\Channel;
// Get only the default channel
Channel::query()->default()->first();
// Get only enabled channels
Channel::query()->enabled()->get();
// Combine scopes
Channel::query()
->enabled()
->where('timezone', 'UTC')
->get();Observer Behavior
The Shopper\Core\Observers\ChannelObserver ensures only one channel can be default:
// When creating/updating a channel with is_default = true:
// 1. Any existing default channel is set to is_default = false
// 2. The new/updated channel becomes the default
$channel = Channel::query()->create([
'name' => 'Mobile App',
'is_default' => true, // Previous default is automatically unset
]);The previous default is updated with updateQuietly(), so no model events fire for it. The observer does not keep a default in place: setting is_default to false on the current default leaves the store without one.
Default Channel
When you accept the database step of php artisan shopper:install, the ChannelSeeder creates one channel named Web Store, with the slug web-store, the url from config('app.url'), enabled and marked as default.
You can retrieve the default channel using the default scope. It returns null when no channel is marked as default:
use Shopper\Core\Models\Channel;
use Shopper\Models\Product;
// Get the default channel
$channel = Channel::query()->default()->first();
// Use in controllers
public function index()
{
$channel = Channel::query()->default()->first();
$products = Product::query()
->forChannel($channel->id)
->publish()
->get();
}Creating Channels
The 2.x admin panel has no page to manage channels: create them in code, for example in a seeder. is_enabled defaults to false, so pass 'is_enabled' => true for a channel you want to pick in the admin product form.
Default Website Channel
Creating a channel with 'is_default' => true removes the flag from the current default, such as the seeded Web Store channel.
use Shopper\Core\Models\Channel;
$channel = Channel::query()->create([
'name' => 'Website',
'slug' => 'website',
'description' => 'Main e-commerce website',
'url' => config('app.url'),
'timezone' => config('app.timezone'),
'is_default' => true,
'is_enabled' => true,
]);Additional Channels
// Mobile app channel
$mobileChannel = Channel::query()->create([
'name' => 'Mobile App',
'slug' => 'mobile-app',
'description' => 'iOS and Android mobile application',
'timezone' => 'UTC',
'is_enabled' => true,
]);
// Marketplace channel
$marketplaceChannel = Channel::query()->create([
'name' => 'Amazon',
'slug' => 'amazon',
'description' => 'Amazon marketplace integration',
'url' => 'https://amazon.com/store/your-store',
'is_enabled' => true,
'metadata' => [
'marketplace_id' => 'ATVPDKIKX0DER',
'seller_id' => 'A1234567890',
],
]);Retrieving Channels
use Shopper\Core\Models\Channel;
// Get all enabled channels
$channels = Channel::query()->enabled()->get();
// Get default channel
$default = Channel::query()->default()->first();
// Get channel by slug
$channel = Channel::query()
->where('slug', 'website')
->first();
// Get channel by slug, throws ModelNotFoundException when none matches
$channel = Channel::findBySlug('website');
// Get channel with products
$channel = Channel::query()
->with('products')
->where('slug', 'mobile-app')
->first();
// Get channels with product counts
$channels = Channel::query()
->enabled()
->withCount('products')
->get();Assigning Products to Channels
use Shopper\Models\Product;
$product = Product::query()->find($id);
// Assign to channels (via product)
$product->channels()->attach([$channelId1, $channelId2]);
// Get products for a specific channel
$products = Product::query()
->forChannel($channelId)
->publish()
->get();
// Get products assigned to at least one of these channels
$products = Product::query()
->forChannel([$channelId1, $channelId2])
->publish()
->get();Storefront Example
namespace App\Http\Controllers;
use Shopper\Core\Models\Channel;
use Shopper\Models\Product;
class ProductController extends Controller
{
public function index()
{
// Get products for default channel
$channel = Channel::query()->default()->first();
$products = Product::query()
->forChannel($channel->id)
->publish()
->with(['brand', 'categories'])
->paginate(12);
return view('products.index', compact('products'));
}
}Multi-Channel API
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Shopper\Core\Models\Channel;
use Shopper\Models\Product;
class ProductController extends Controller
{
public function index(Request $request)
{
$channelSlug = $request->header('X-Channel', 'website');
$channel = Channel::query()
->where('slug', $channelSlug)
->enabled()
->firstOrFail();
$products = Product::query()
->forChannel($channel->id)
->publish()
->paginate(20);
return response()->json($products);
}
}Use Cases
| Channel | Example Use |
|---|---|
| Website | Main e-commerce storefront |
| Mobile App | iOS/Android application |
| Marketplace | Amazon, eBay, Etsy integration |
| POS | Physical store point of sale |
| Wholesale | B2B customer portal |
| Social | Facebook/Instagram shop |
Best Practices
- Default Channel: Always have one default channel for fallback
- Product Assignment: Assign products to relevant channels during creation
- Timezone: Shopper stores
timezonebut does not read it: use it in your own code (for example to show order dates in the channel's timezone) - Metadata: Use metadata for channel-specific configuration (marketplace or seller IDs). Keep secrets such as API keys in
.env, not in a database column
// Example: Channel-specific settings
$channel = Channel::query()->find($id);
$marketplaceId = $channel->metadata['marketplace_id'] ?? null;
$sellerId = $channel->metadata['seller_id'] ?? null;Last updated on
Edit on GitHub