Keeps your Oyster catalogue in step with any store. Call it with an API key that has
catalogue:write (Manage catalogue), or with an Oyster Shopify or WooCommerce store connection.
Dashboard sessions and widget tokens are refused.
Identifying a product. Each row is matched by sku, by the store's own
external_product_id and external_variant_id, or both. Store ids need a platform: a
store connection uses its own, and an API key may declare shopify or woocommerce when it
integrates one of those stores itself. Store ids link the product to that store, which lets a
product without a SKU sync (Oyster assigns it a SKU) and lets the stock and archive calls name
it by store id. A row with store ids and a SKU that matches an existing product links that
product (claimed) and keeps the details curated in Oyster, taking only its stock.
What is written. An unknown product is created and published; a known one is updated.
Fields you omit are left as they are. A new product with no stock_level starts at 0.
Out-of-stock products rank below in-stock ones; if you don't track quantities, send any positive
number while a product is in stock and 0 when it isn't. Ingredients and skin types are taken
when a product is created or has none, and are then the vendor's to edit in Oyster. A product
you archived through this API is published again when you upsert it; a draft stays a draft.
Two stores, one product. When a vendor connects more than one store, the primary store
owns a shared product's details. Another store still records its own price and stock against it
(listed). A row with no store ids for a product a connected store sells is reported as
managed_by_connected_store and left alone. Products in a category Oyster does not carry are
skipped (off_range) and removed if present.
Each row succeeds or fails on its own; one bad row never costs the batch. 200 when every row
was saved, 207 when any failed. Up to 250 rows per call, each product once. Safe to retry a
transport failure, 429 or 5xx with the same body.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
401Missing or expired API key
403Not an API key or store connection, or the key lacks catalogue:write
422The request is malformed and nothing was saved: a missing name, price, or both SKU and
store id; store ids without a platform (platform_required_for_store_ids); a store
connection declaring another platform (platform_mismatch); or a product sent twice
(duplicate_in_batch).