Skip to content

Suppliers

Complete reference for the Supplier model, product sourcing, and dropshipping integration in Shopper.

Suppliers represent external vendors or manufacturers who provide products for your store. This is primarily used in dropshipping scenarios where products are shipped directly from the supplier to the customer, without you handling inventory.

The supplier feature is gated behind a feature flag and is disabled by default. It must be enabled in your config/shopper/features.php configuration file.

Model

The model used is Shopper\Core\Models\Supplier. It implements Shopper\Core\Models\Contracts\Supplier and uses the HasSlug trait: a slug you set is passed through Str::slug() and gets a numeric suffix (-1, -2) when another supplier already uses it. The trait does not create a slug from the name: the admin form fills it from the name, and in code you pass it yourself. HasSlug also adds Supplier::findBySlug(). 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\Supplier as BaseSupplier;

class Supplier extends BaseSupplier
{
}

Update config/shopper/models.php:

return [
    'supplier' => \App\Models\Supplier::class,
];

Feature Flag

Enable the supplier feature in config/shopper/features.php:

use Shopper\Enum\FeatureState;

return [
    // ...
    'supplier' => FeatureState::Enabled,
];

When enabled, the Suppliers page appears under Products in the admin sidebar (route shopper.suppliers.index), and the edit page of External products shows a required supplier select that lists only enabled suppliers. The flag only controls the admin: the suppliers table, the model and its relationships exist either way.

Database Schema

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
namestringno-Supplier name
slugstringyesnullURL-friendly identifier (unique)
emailstringyesnullContact email
phonestringyesnullContact phone
contact_namestringyesnullPrimary contact person
websitestringyesnullSupplier website URL
descriptionlongTextyesnullDetailed description
noteslongTextyesnullInternal notes
is_enabledbooleannofalseWhether the supplier is active (only enabled suppliers can be picked on a product)
metadatajsonbyesnullAdditional custom data
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast update timestamp

Relationships

Products

A supplier can have many products linked to it:

// Get all products from a supplier
$supplier->products; // Collection<Product>

// Get visible products
$supplier->products()
    ->where('is_visible', true)
    ->get();

// Count products per supplier
$supplier->products()->count();

Product to Supplier

Each product can optionally belong to one supplier:

use Shopper\Models\Product;

// Get a product's supplier
$product->supplier; // Supplier (nullable)

// Check if a product has a supplier
if ($product->supplier_id) {
    // This is a dropshipped product
}

// Get all products from a specific supplier
Product::query()
    ->where('supplier_id', $supplier->id)
    ->get();

Query Scopes

use Shopper\Core\Models\Supplier;

// Get only enabled suppliers
Supplier::query()->enabled()->get();

Creating Suppliers

use Shopper\Core\Models\Supplier;

$supplier = Supplier::query()->create([
    'name' => 'TechParts Co., Ltd',
    'slug' => 'techparts-co',
    'email' => 'orders@techparts.com',
    'phone' => '+86 755 1234 5678',
    'contact_name' => 'Zhang Wei',
    'website' => 'https://techparts.com',
    'description' => 'Electronics components and accessories manufacturer based in Shenzhen.',
    'notes' => 'Minimum order: 50 units. Lead time: 5-7 days.',
    'is_enabled' => true,
    'metadata' => [
        'payment_terms' => 'net_30',
        'currency' => 'USD',
        'minimum_order' => 50,
    ],
]);

Updating Status

updateStatus() takes a boolean that defaults to true:

// Enable a supplier
$supplier->updateStatus();

// Disable a supplier
$supplier->updateStatus(false);

Retrieving Suppliers

// Get all enabled suppliers
$suppliers = Supplier::query()
    ->enabled()
    ->withCount('products')
    ->get();

// Find by slug (throws ModelNotFoundException when missing)
$supplier = Supplier::findBySlug('techparts-co');

// Search enabled suppliers by name or email
$results = Supplier::query()
    ->enabled()
    ->where(function ($query) use ($search): void {
        $query->where('name', 'like', "%{$search}%")
            ->orWhere('email', 'like', "%{$search}%");
    })
    ->get();

Linking Products to Suppliers

The admin shows the supplier field on products of type External only. The link is stored in the nullable supplier_id column of the products table:

use Shopper\Core\Enum\ProductType;
use Shopper\Models\Product;

// Create an external product linked to a supplier
$product = Product::query()->create([
    'name' => 'Wireless Bluetooth Earbuds',
    'slug' => 'wireless-bluetooth-earbuds',
    'type' => ProductType::External,
    'supplier_id' => $supplier->id,
    'is_visible' => true,
    // ... other product fields
]);

// Change a product's supplier
$product->update(['supplier_id' => $newSupplier->id]);

// Remove supplier link
$product->update(['supplier_id' => null]);

Deleting a supplier does not delete its products: the foreign key sets their supplier_id to null.

Dropshipping Workflow

The supplier feature is designed to work with the Fulfillment system. Here's the complete flow:

1. Setup

use Shopper\Core\Models\Supplier;

// Create your supplier
$supplier = Supplier::query()->create([
    'name' => 'Shenzhen TechParts',
    'slug' => 'shenzhen-techparts',
    'email' => 'orders@techparts.com',
    'is_enabled' => true,
]);

// Link products to supplier
$product->update(['supplier_id' => $supplier->id]);

2. Customer Places Order

When a customer orders a product linked to a supplier, the order is created normally. The item's fulfillment_status starts as Pending.

3. Forward to Supplier

After receiving the customer's payment, you place the order with your supplier using the customer's shipping address:

use Shopper\Core\Enum\FulfillmentStatus;

// Mark this supplier's items as forwarded
$order->items()
    ->where('fulfillment_status', FulfillmentStatus::Pending)
    ->whereHasMorph(
        'product',
        [config('shopper.models.product')],
        fn ($query) => $query->where('supplier_id', $supplier->id),
    )
    ->update(['fulfillment_status' => FulfillmentStatus::ForwardedToSupplier]);

An order item's product is a polymorphic relation that points to a product or a variant, and only products have a supplier_id column. whereHasMorph() limits the check to products. Only Variant products have variants, so the items of an External product always point to the product itself.

4. Supplier Ships

When the supplier provides tracking information, create the shipment and attach this supplier's forwarded items to it:

use Shopper\Core\Actions\SyncOrderShippingStatusAction;
use Shopper\Core\Enum\FulfillmentStatus;
use Shopper\Core\Enum\ShipmentStatus;

$shipment = $order->shippings()->create([
    'carrier_id' => $carrierId,
    'status' => ShipmentStatus::PickedUp,
    'tracking_number' => $supplierTracking,
    'tracking_url' => $supplierTrackingUrl,
    'shipped_at' => now(),
]);

$order->items()
    ->where('fulfillment_status', FulfillmentStatus::ForwardedToSupplier)
    ->whereHasMorph(
        'product',
        [config('shopper.models.product')],
        fn ($query) => $query->where('supplier_id', $supplier->id),
    )
    ->update([
        'order_shipping_id' => $shipment->id,
        'fulfillment_status' => FulfillmentStatus::Shipped,
    ]);

(new SyncOrderShippingStatusAction)->execute($order);

The items are updated here because RecordShipmentEventAction only moves Pending items to Shipped. SyncOrderShippingStatusAction recomputes the order's shipping_status and dispatches OrderShipped when it becomes Shipped.

5. Delivery Confirmation

$shipment->update([
    'status' => ShipmentStatus::Delivered,
    'received_at' => now(),
]);

$shipment->items()->update([
    'fulfillment_status' => FulfillmentStatus::Delivered,
]);

(new SyncOrderShippingStatusAction)->execute($order);

Querying by Supplier

use Illuminate\Support\Facades\DB;
use Shopper\Core\Enum\FulfillmentStatus;
use Shopper\Core\Models\OrderItem;

// Get the items still waiting on a supplier
$pendingItems = OrderItem::query()
    ->whereIn('fulfillment_status', [
        FulfillmentStatus::Pending,
        FulfillmentStatus::ForwardedToSupplier,
    ])
    ->whereHasMorph(
        'product',
        [config('shopper.models.product')],
        fn ($query) => $query->where('supplier_id', $supplier->id),
    )
    ->with(['order.customer', 'order.shippingAddress'])
    ->get();

// Get supplier revenue in cents (delivered items, after item discounts)
$revenue = OrderItem::query()
    ->whereHasMorph(
        'product',
        [config('shopper.models.product')],
        fn ($query) => $query->where('supplier_id', $supplier->id),
    )
    ->where('fulfillment_status', FulfillmentStatus::Delivered)
    ->sum(DB::raw('unit_price_amount * quantity - discount_amount'));

Permissions

The supplier feature uses the following permissions:

PermissionDescription
browse_suppliersView the suppliers list and its sidebar entry
read_suppliersNot checked by the admin (there is no supplier detail page), available to your own code
add_suppliersCreate new suppliers
edit_suppliersUpdate existing suppliers, enable or disable them in bulk
delete_suppliersDelete suppliers
// Check permission
$user->hasPermissionTo('browse_suppliers');

// Assign permission to a role
$role->givePermissionTo('browse_suppliers');

The installer creates these permissions in the products group. On a store installed before the supplier feature existed, create them before you enable the feature, then assign them to your roles:

use Shopper\Models\Permission;

Permission::generate('suppliers', 'products');

Components

The supplier feature registers its components through the product configuration. Publish the product components to customize:

php artisan shopper:component:publish product

This includes:

// In config/shopper/components/product.php
use Shopper\Livewire;

return [
    'pages' => [
        'supplier-index' => Livewire\Pages\Supplier\Index::class,
        // ...
    ],
    'components' => [
        'slide-overs.supplier-form' => Livewire\SlideOvers\SupplierForm::class,
        // ...
    ],
];

The SupplierForm slide-over handles both creating and editing a supplier. To add content above or below the suppliers table without publishing components, use the SalesRenderHook::SUPPLIERS_TABLE_BEFORE and SalesRenderHook::SUPPLIERS_TABLE_AFTER render hooks.

Metadata

The metadata column (JSON) can store any additional supplier-specific data:

$supplier = Supplier::query()->create([
    'name' => 'FastShip Logistics',
    'slug' => 'fastship-logistics',
    'metadata' => [
        'payment_terms' => 'net_30',
        'currency' => 'USD',
        'minimum_order' => 100,
        'lead_time_days' => 7,
        'return_policy' => '30 days',
        'api_endpoint' => 'https://api.fastship.com/v2',
    ],
]);

// Access metadata
$terms = $supplier->metadata['payment_terms'];

The supplier form in the admin edits metadata as key-value text pairs. Keep values flat (no nested arrays) so they stay editable there, and expect values saved from the form to come back as strings.

Last updated on

Edit on GitHub