Catalog and stock

The catalog is the seller's base. It says what the seller sells, with no price and no marketplace. Listings use this base but never change it. The full model, with diagrams: Catalog and inventory.

1. Product and variantCopy Anchor Link

• Product is the item: title, brand, description, attributes, tax and compliance data.
• Variant is the combination that sells: the black iPhone 16 · 128 GB. It has its own SKU, GTIN, weight and size, for the item and for the package.
• Every Product is born with a default Variant. You create the others later.

Tax data is typed: ncm, cest, origin, CFOP, CST/CSOSN and PIS/COFINS. So are attributes: each one has a key and a typed value (text, number with unit, list, yes/no…). That way the same attribute works for every marketplace.

Weight is always in grams and size in millimeters, as integers: weightInGrams: 170, dimensionsInMm: { length: 147, width: 72, height: 8 }.

2. KitsCopy Anchor Link

A kit is a Product whose Variant uses up others. Acme Store's charging kit takes 2 cables and 1 charger. You save the recipe in components. The kit's balance is computed: with 10 cables and 3 chargers in the same warehouse, there are 3 kits. A kit is not assembled from parts that sit in two places, so the calculation is done warehouse by warehouse.

3. Photos and videosCopy Anchor Link

A file goes in through the API in two steps:

1. You ask for an upload URL (valid for 15 minutes) and send the file to it.
2. You confirm. marketapi checks the type by the content and only then accepts the file.

You can also bring a file from a public URL, in a job. Then you link the media to the Product or the Variant. To take that media to listings already created, ask for a propagation: it never happens on its own.

Documents with personal data, such as the NF-e XML and the shipping label, are confidential: they never have a URL and only come out through the API, with your key. See Assets and media.

4. WarehousesCopy Anchor Link

Every seller has a default warehouse, created on its own. If they keep stock in more than one place, create others. The balance is per Variant in each warehouse, and the Variant's balance is the sum.

• A movement without warehouseId goes to the default warehouse.
• A warehouse is never deleted: it is archived. The default one, and a warehouse that still has balance, cannot be archived.

5. Who owns the stockCopy Anchor Link

Choose, on each Variant, where the truth of the balance comes from:

Pick a single owner. If the ERP and marketapi both count the same sale, the balance drifts.

6. Movements and balanceCopy Anchor Link

With marketapi, stock only changes through a movement: adjustment, reservation, release, sale, return or transfer. A movement never changes after it is created. The balance has three numbers:

Example: Acme Store receives 100 black iPhones (adjustment +100). A paid order reserves 1: onHand 100, reserved 1, available 99. When the order ships, the reservation becomes a sale: onHand 99, reserved 0.

To take units from one warehouse to another, use transfer: it writes an outbound at the source and an inbound at the destination, with the same transferId. The Variant total does not change. If the warehouse does not have enough stock, the API responds 409 (inventory_underflow) and writes nothing.

With orders turned on, marketapi creates the reservation, the sale and the release on its own. See The order lifecycle.

Endpoints in this phaseCopy Anchor Link

Webhooks in this phase: product.created, product.updated, product.archived, variant.created, variant.updated, variant.archived, inventory.movement_created, warehouse.created, warehouse.updated, warehouse.archived, asset.ready and asset.failed.