Skip to main content
Programmatic equivalent of the dashboard’s products/<gtin>/offers/ page.

​
When to use

  • A brand owner needs to record which physical stores and which websites sell a product, at what price and with what availability.
  • An offer on file is out of date (a price, a status, a stock level) and needs correcting.

​
Auth

X-API-Key header or OAuth token. Writing an offer takes the Manage offers (MANAGE_OFFERS) permission on the organization, which a member with the Editor, Manager or Owner role holds, and so does an API key with the Editor or Manager role. A read-only key is refused. Every refusal answers 404, not 403, so the API never confirms that another organization or its offers exist.

​
Find the store first

An offer names one store by id. Look it up; never create one from this workflow.
A shared (Closient-curated) retailer’s stores are open to every organization. Another organization’s private retailer is not: an offer at one of its stores answers 404.

​
Flow

Online offers use the same shapes under online-offers.
  • List — paginated. The default lists the offers this organization submitted; scope=on_products adds the ones other organizations submitted on its products.
  • Create — the body names the product with product_id and the store with physical_store_id (in-store) or online_store_id (online); fields are listed in the OpenAPI document at /retailers/api/v1/openapi.json. A new offer starts active; the (product_id, store_id, sku) triple must be unique (422 otherwise). Creation is rate-limited per organization (429 with retry_after).
  • Update — PUT with the fields to change; the body also accepts status. Only the organization that submitted an offer may update it.
  • Delete — the submitting organization may delete an offer, and so may the organization that owns the product while the offer is another organization’s unverified submission: a brand can remove such an offer on its product, but never rewrite it. Once Closient has verified an offer, only its submitter can delete it.
  • Read back — every write returns the saved offer; GET it again to confirm.

​
Promotions

A promotion hangs off one offer and follows that offer’s permission:
Online promotions use the same shapes under online-offers and online-promotions.

​
Notes

Returns 404 for a read-only key, another organization’s offer or private store, or a product or store that does not exist; 422 for an invalid value. An offer on a product another organization owns is stored but hidden from public surfaces until Closient verifies it. The fields an organization writes on an offer are defined once on the model (EDITABLE_FIELDS).