Mixed shipping / collection / digital fulfilments, and renaming shipping “In Progress”

[wychoong]

Two questions from extending fulfilment: mixed baskets, and what shipping In Progress actually means.

Mixed methods on one order

Docs say a mixed basket becomes one fulfilment per method:

When an order is placed, Lunar automatically creates its initial fulfilments: each registered fulfilment method claims the lines it covers, in priority order, and a method that claims at least one line gets one fulfilment covering them. A basket of a shippable product, a licence key, and a click-and-collect item ends up with three fulfilments — one per method.

— Fulfilments

Claim rules:

Method	Priority	Claims
Digital	10	requires_fulfilment && !requires_shipping
Collection	20	requires_shipping lines, only when the order's shipping option was a collection
Shipping	30	remaining requires_shipping lines

Collection is all-or-nothing on the order, not per line:

// packages/core/src/Drivers/FulfilmentMethods/Collection.php
public function claim(Order $order, SupportCollection $unclaimed): SupportCollection
{
    if (! $this->orderCollects($order)) {
        return $unclaimed->take(0);
    }

    return $unclaimed->filter(fn ($line) => $line->requires_shipping)->values();
}

If collect === true on the shipping line, collection takes every physical line. Shipping gets nothing. So shippable + licence + click-and-collect does not produce three fulfilments — you get collection + digital. You cannot ship some lines and collect others on the same order, because checkout has one shipping option.

Split/merge do not change method. Split copies the source method; merge requires the same method:

// packages/core/src/Actions/Fulfilment/SplitFulfilment.php
// The split-off fulfilment inherits the source's method and state —
// splitting only reorganises outstanding quantities, so a fulfilment
// already being prepared shouldn't drop back to its default state,
// and a collection/digital fulfilment must stay that method.

// packages/core/src/Actions/Fulfilment/MergeFulfilments.php
if ($source->method !== $target->method) {
    return 'lunar::exceptions.fulfilment_method_mismatch';
}

Split does cover "ship in-stock now, rest later" as two shipping fulfilments. It does not cover "pickup these, ship those."

Questions:

1. Is mixed pickup + delivery on one order in scope, or must checkout stay one method for all physical lines?
2. If it is in scope, should checkout submit split fulfilments (per-line method), or is that always a merchant split after place?
3. Should the docs example be corrected? As implemented, that basket is two fulfilments, not three.

Shipping InProgress vs collection, and room to extend

In source, shipping InProgress is still Outstanding — goods have not left, ship() has not run, split/merge/hold still apply, no stock ship, no shipped_at. Spec 0022 names that step picking/packing. The public docs only list the state; they do not say warehouse vs in transit.

// packages/core/src/States/Fulfilment/InProgress.php
public static string $name = 'in-progress';

public function category(): FulfilmentStateCategory
{
    return FulfilmentStateCategory::Outstanding;
}

English label is In Progress. You can skip it (Pending → Shipped). Collection's analog is named for what is happening; shipping's is not:

• Shipping: Pending → InProgress → Shipped
• Collection: Pending → ReadyForCollection → Collected

ReadyForCollection is explicit (picked/packed, waiting at the counter):

// packages/core/src/States/Fulfilment/ReadyForCollection.php
 * A collection fulfilment is picked, packed and waiting at the counter for the
 * customer to pick up — the collection flow's outstanding "in-progress" step.

A label like Preparing (pick/pack) would sit next to Ready for collection: both Outstanding, both "we are working this parcel," neither "handed over." Shipped / Collected stay the hand-over states.

Clear names also leave room to extend the shipping graph later without overloading one bucket:

Step	Role
Preparing (today's InProgress)	Pick and pack, still in the warehouse
In transit / Dispatched (new, if needed)	Left the warehouse, not delivered
Shipped	Handed to the carrier (current Fulfilled terminal)

If InProgress stays the label for pick-and-pack, adding In transit/Dispatched collides with what people already think "in progress" means. Renaming (or documenting) it as Preparing keeps pick-and-pack distinct from anything that happens after the parcel leaves.

Refs:

• https://github.com/lunarphp/lunar/blob/2.x/packages/core/src/Drivers/FulfilmentMethods/Collection.php
• https://github.com/lunarphp/lunar/blob/2.x/packages/core/src/Actions/Fulfilment/SplitFulfilment.php
• https://github.com/lunarphp/lunar/blob/2.x/packages/core/src/Actions/Fulfilment/MergeFulfilments.php
• https://github.com/lunarphp/lunar/blob/2.x/packages/core/src/States/Fulfilment/InProgress.php
• https://github.com/lunarphp/lunar/blob/2.x/packages/core/src/States/Fulfilment/ReadyForCollection.php
• https://docs.lunarphp.com/2.x/reference/fulfilments.md