Matching External Items to Peasy Items
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 and during the Item Review step for reusable spreadsheet data imports.
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 small status labels or dots to show what will happen:
- New family — Peasy will create a new item family.
- New 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, click Help above the staging table to open the Inventory Grouping Settings drawer and Beacon guidance.
The drawer has two options:
- Shared Inventory Pools — variants from the same external product roll up into one Peasy item family. 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.
The Example Only section previews the card structure Peasy will use. It does not save anything; it just shows how external items would be grouped as Peasy item families and variants.
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.
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.
The footer button changes scope based on what you're viewing or selecting, such as Save All, Save Page, or Save Selected. Searching, filtering, or selecting rows changes which external items are included.
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.
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.
