Products and variants
Reusable base records, sellable variants, and kits.
A Product is the reusable local base record. A Variant is the unit that can actually be sold, reserved, and stocked: it has its own SKU, GTIN, options, and inventory policy. A Listing is different: it is one concrete offer in one marketplace Connection. Multiple ads — including A/B experiments in the same channel — can reuse the same Variants.
The full model of Product, Variant and kit, with diagrams: Catalog and inventory.
In other words: the product describes what exists; the variant describes which combination is sellable; the listing describes how and where it is offered. The marketplace never edits this base. External facts live in the listing's observed; a local edit is sent only when you explicitly publish that Listing.
Recommended end-to-end flow
- Create the Product with stable data: brand, model, base description, physical details, and reusable media.
- Update the automatically created standard Variant or create Variants for each sellable combination. For an iPhone 16,
black/16 GB,white/16 GB, andblack/32 GBare three Variants with three independent balances. - Set each Variant's
inventoryAuthority. Usemarketapionly when this API owns the ledger; usederivedfor a kit Variant; keepmanaged_externallywhen the ERP is authoritative. - For a kit, replace its complete BOM. Kit availability is the smallest whole-number ratio available across its components.
- Record or inspect balance in Inventory. Then create a Listing, bind its Variants, and publish when you decide to.
What belongs at each level
| Question | Correct place |
|---|---|
| “What is this product: brand, model, reusable description?” | Product |
| “Which color/storage/SKU/GTIN has its own availability?” | Variant |
| “Which title, price, media, and commercial rules apply to this offer?” | Listing.desired |
| “What did the marketplace confirm exists remotely?” | Listing.observed |
Every Product starts with a standard Variant, with no SKU and disabled
inventory. It ensures that even a simple product has a sellable unit. Update
it when the product has no options; create additional Variants for
combinations such as color, size, or storage.
Inventory and kits in practice
marketapi: immutable movements form the ledger and calculateonHand,reserved, andavailable.managed_externally: another system owns the balance; MarketAPI rejects local movements for this Variant.derived: it receives no movement of its own. Its balance is derived from the Product BOM, such asmin(cables ÷ 2, chargers ÷ 1)for a kit that consumes two cables and one charger.disabled: the Variant has no API-managed quantity.
Archiving never deletes history, movements, or audit data. Before archiving a Product or Variant, deliberately remove any Listing bindings that still use it.
Photos and videos are Assets: upload the file first and use its assetId in media. The asset must belong to the same seller.