Concepts

Match or propose

Wamia is a single catalogue: one product, many offers. apiMatchListings takes your SKUs with their GTIN, brand, MPN and title and answers, per SKU, a match with its confidence (gtin, brand_mpn, …) or unmatched. Attach an offer to a match with apiUpsertOffers; for an unmatched SKU, apiSubmitListing proposes a new product, which enters the approval pipeline as a draft with the images you give by URL and becomes a product once a moderator — or the shop’s trust score — approves it. Content changes on a live product go through apiProposeListingEdit.

Never create duplicates on purpose: matched products reach the Buy Box immediately, proposed ones wait for review.

Approval pipeline and trust

Each proposal is checked for completeness (mandatory attributes of the family, at least one image), then reviewed. Shops with a high trust score are auto-approved; moderation notes come back in ApiListingView.moderationNotes and as listing.state_changed webhooks. Fix the notes and resubmit; the SKU keeps its history.

Media

Images are copied into Wamia storage: pass public https URLs to apiIngestMediaFromUrls (up to 20 per call) and Wamia fetches them asynchronously — apiMyMediaImports reports progress — or request a 15-minute signed upload with apiCreateMediaUpload and seal it with apiFinalizeMediaUpload. Attach assets to a product with apiAssignProductMedia. Private networks, redirects to them, files above 10 MB and non-image types are refused with MEDIA_FETCH_REFUSED.

Guardrails

Circuit breakers protect the shop from its own bugs: a bulk price change that moves more than the configured share of listings by more than the configured percentage, or a stock update that zeroes too many SKUs at once (five listings or more), is held instead of applied. The call answers BATCH_HELD with extensions.pendingBatchId, the shop gets a connect.batch_held webhook and a dashboard card, and the plugin can list held batches with apiPendingBatches and settle them with apiConfirmBatch or apiDiscardBatch. Nothing in the batch is applied until then; held batches expire after 7 days.

Dry-run

Send Wamia-Dry-Run: true on any mutation to validate the payload, run the guardrails and get the per-item outcome without writing. Connectors use it for the import wizard preview; use it before your first real bulk call.

Cursors and reconciliation

Lists are cursor-paginated and accept updatedSince; poll apiMyListings(updatedSince) nightly and compare with your own records, or call apiReconcileReport for a summary of mismatches Wamia found between what you last sent and what it holds. Webhooks are at-least-once; reconciliation is how you stay exact.

Orders

A Wamia order is split into slices, one per shop and facility. Your plugin mirrors the slice as a local order (apiMyOrdersPage, apiMyOrderSlice), acknowledges it with apiAcknowledgeSlice, marks it prepared with apiMarkSlicePrepared and follows the carrier through apiShipments. Returns arrive as RMAs (apiMySliceReturnsPage) and the shop answers with apiDecideReturn.