Create or update products in your Oyster catalogue

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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string | null
enum

The store your ids belong to. A store connection uses its own; an API key declares it to send store ids.

Allowed:
products
array of objects
required
length between 1 and 250
products*
Responses

401

Missing or expired API key

403

Not an API key or store connection, or the key lacks catalogue:write

422

The 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).

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json