Matching External Items to Peasy Items

IntegrationsUpdated August 19, 2026 · Reviewed by Peasy Team

When Peasy imports products or line items from another system, it needs to know whether each external item should become a new Peasy item or connect to something that already exists. Matching prevents duplicates and keeps inventory, sales, purchases, and sync links tied to the right item family.

You'll see this during Shopify product imports, when importing orders from Faire, Shopify, Amazon, or a spreadsheet, and during the Item Review step for reusable spreadsheet data imports. Order imports from every source share this same review — Faire is just one of the sources, not a separate system — so the steps below apply the same way no matter where the orders came from.

How to Get There

You reach this review whenever Peasy stages imported data for you to confirm:

  • Product imports — during a Shopify product import.
  • Order imports — after importing orders from Faire (Configure > Beta > Faire > Import orders), Shopify, Amazon, or a spreadsheet. Peasy stages the orders and takes you to the data import review page.
  • Reusable spreadsheet imports — in Configure > Data Imports, on a staged run's review page.

Item Families and Variants

An item family is the product Peasy tracks as one inventory pool. A family can have multiple variants: different units, pack sizes, suppliers, sales formats, or conversion-only units that all draw from the same underlying count.

Use one family when the formats are interchangeable through unit conversion:

  • A 12-oz bag, a 3-pack of those bags, and a case of twelve bags
  • The same ingredient from multiple suppliers
  • A pallet, case, and each that all represent the same stock

Use separate families when the products have separate inventory pools or need production work between them:

  • Different colors, flavors, sizes, or SKUs that cannot substitute for each other
  • A 12-oz bag and a 1-lb bag when you would need to rebag product to fulfill the order
  • Finished goods and the raw materials or ingredients used to make them

Statuses You May See

The staging cards use status pills to show what will happen:

  • Add family — Peasy will create a new item family.
  • Add variant — Peasy will add a new variant under a family.
  • Match — The external item is set to link to an existing Peasy item or family.
  • Saved — The external item has already been saved into Peasy.
  • Mixed — A family has some saved items and some items still waiting for review.

Choosing the Grouping

On product import screens, open the ⋮ menu above the staging table and choose Inventory grouping. The Help button opens Beacon guidance instead.

The drawer has two options:

  • Shared Inventory Families — Group items into families to share the same inventory pool. Choose this when the variants are different ways to count, buy, or sell the same stock.
  • Separate Items — each external variant becomes its own Peasy item family with its own count. Choose this when the variants are distinct products that should not share inventory.

Matching or Creating

For each external item, decide which of these is true:

  • It already exists in Peasy. Match it to the existing family or variant so Peasy links the external item instead of creating a duplicate.
  • It is the same inventory pool as an existing family, but a new unit or format. Add it as a new variant in that family.
  • It is a different product or inventory pool. Let Peasy create a new family.

If you're unsure, ask whether inventory should move together. If selling one format should reduce the same stock as another format, they usually belong in the same family. If they need separate counts, separate families are safer.

For Shopify product imports, several source variants may match the same Peasy sell variant when they are truly aliases for the same unit and conversion. The review shows when a Peasy variant already has Shopify mappings, but it still lets you select it. Each Shopify identity remains a separate link, so unlinking one does not remove the others.

Saving Reviewed Items

The staging page uses Save actions. A Save can create new Peasy items, link matched external items to existing Peasy items, or do both at once.

Save from a family header to save every pending variant in that family. If you select some pending variants in that family first, the button changes to Save N variants and saves only that selection. The footer's Save N Families button saves the ready families on the currently loaded page. If your import has more pages, move to each page to review and save its families; selecting individual variants does not change the footer save scope.

Use Exclude variant for a source variant you do not want to save. Excluded variants remain available in the Excluded variants section and can be restored later.

Each new variant needs a unit before it can be saved. Until you choose one from its unit selector, that variant shows a placeholder and the family save stays disabled with a prompt to pick a unit (or exclude the variant). A variant matched to an existing Peasy item inherits that item's unit, so it doesn't need a choice.

Spreadsheet Item Review

Reusable spreadsheet data imports use the same matching idea, but the external items are line-item names or SKUs from a CSV, Excel, or pasted spreadsheet.

When you match a spreadsheet line item to a Peasy item, Peasy remembers that mapping for future uploads from the same data import. Records without required item mappings cannot be finalized, because Peasy needs to know which item each bill or sales order line refers to.

Order Line Units and Quantities

When you import orders — from Faire, Shopify, Amazon, or a spreadsheet — each order line's quantity counts against whichever Peasy variant you match the line to, and that variant's unit decides how the number is read.

Some sources send an order line as a plain quantity with no unit attached. A Faire order, for example, can send a quantity of "2" without saying whether that's 2 cases or 2 eaches. Peasy takes the unit from the variant you match the line to, so the match matters:

  • Match a line that was ordered by the case to the case variant, not to the each or base-unit variant.
  • If you match a case line to an "each" variant, the quantity can look far too high or too low once it flows into pending inventory.

If pending inventory or order quantities look off after an order import, check that each line is matched to the variant whose unit matches how it was actually ordered.

Choosing the Buyer for Order Imports

A staged sales order also needs a buyer before Peasy can finalize it. Peasy determines the buyer from one of three things:

  • A customer name on each order — when the import carries a per-order customer name, matched to your Peasy customers.
  • One customer for the whole import — you choose a single customer that all the staged orders belong to.
  • A sales channel as the buyer — the order's source channel stands in as the buyer.

Marketplace buyers, like Faire retailers, are not created as Peasy customers automatically. If a staged order can't be tied to a customer or channel, the import is blocked until you resolve the buyer — match the retailer to an existing customer, choose a customer for the import, or set the source's sales channel. Until every staged order has a buyer, it can't be committed.

Good to Know

  • Matching is non-destructive. It links the external item to Peasy; it does not delete or overwrite the source item.
  • Creating a new family is best when the item is genuinely new to Peasy.
  • Adding a variant is best when the item is a new format of an existing inventory pool.
  • If the wrong item was saved or linked, use the row or family cleanup actions, such as Unlink, to review it again.

Related

Was this article helpful?