Product matching

A Match records how one or more source ShopItem records map to one or more destination ChannelItem records. Openship uses these saved mappings when an order is configured with matchOrder.

Match records

A match has:

input: the shop-side product ID, variant ID, quantity, shop, and owning user;
output: the channel-side product ID, variant ID, quantity, saved price, channel, and owning user;
an owning user used by access filters and order matching.

The relationships are many-to-many. A one-input, one-output match covers a direct variant mapping; one input with several outputs can represent a bundle.

Create a match

Connect a shop and channel

Configure credentials and verify that both adapter search operations work. Current compiled handlers cover Shopify and Openfront. Other platforms require compatible configured operations.

Search each platform

The Matches workspace calls the selected shop and channel adapters to search products on demand. This is not a background import of either complete catalog.

Select exact items

Choose the source and destination product/variant identities and quantities. Current source does not provide an automatic SKU-matching workflow, so confirm each mapping explicitly.

Save and test

Creating a Match reuses or creates the corresponding ShopItem and ChannelItem records. Route a synthetic order and inspect the generated cart items before enabling downstream purchase creation.

How an order uses matches

When a new order has matchOrder enabled and does not take the separate link-routing path, current source:

loads the order and its line items;
searches matches owned by the same user using product ID, variant ID, and quantity;
first looks for a combined match covering all order lines, then tries individual line matches;
reads each matched destination product through its channel adapter;
creates downstream CartItem records from the saved outputs;
records a price-change error when the current destination price differs from the saved match price;
optionally calls downstream purchase placement when processOrder is enabled.

If no suitable match is found, Openship records a match error and leaves the order for operator handling rather than proving successful fulfillment.

Matching is exact application logic, not probabilistic product identification. Product IDs, variant IDs, quantities, ownership, adapter responses, and current prices must all be tested. Retries and downstream purchase creation also need idempotency and reconciliation coverage before live routing.

Current boundaries

There is no automatic full-catalog import in the current Matches workflow.
There is no implemented automatic SKU-matching action.
Availability- or destination-based selection among several channels is not implemented by the Match lookup.
Inventory synchronization is eligible only for one-input/one-output matches where both quantities are 1 and both adapters expose inventory values.
No checked-in benchmark establishes a supported catalog size or routing throughput.
A saved match does not guarantee that a destination item is still available, unchanged, or purchasable; the channel response and resulting errors still require review.

Product matching

On this page