Create in-store offer
Create a new in-store offer for the given organization. The (product_id, physical_store_id, sku) triple must be unique — sending a duplicate returns 422. Returns 404 when the organization, product, or store does not exist; 404 is also used (rather than 403) when the caller lacks MANAGE_OFFERS to avoid leaking organization existence.
Documentation Index
Fetch the complete documentation index at: https://docs.closient.com/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
Path Parameters
UUID of the organization that will own the offer.
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$Body
Payload for creating a new in-store offer.
product_id and physical_store_id are required; everything else has a
sensible default. The (product, store, sku) triple must be unique — sending
a duplicate will return 422.
UUID of the catalog Product this offer is for. The product must already exist; create it via the products API before adding offers. Immutable after creation — moving a row to a different product means deleting and recreating.
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$UUID of the PhysicalStore (a single brick-and-mortar location, not the parent retailer chain) this offer lives at. The currency on the parent store is what price is denominated in — there is no per-offer currency override.
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$Developer-attached key/value data. Send {} or null to clear. Empty-string values delete that key. Omitted keys are preserved.
Retailer-specific SKU for this product at this store. Empty string when the source doesn't expose a SKU (scraped offers often don't). Together with product_id and physical_store_id this is the row's natural key — the trio must be unique.
100Bare decimal price in the parent store's currency. Omit or send null when the price is unknown; the row will be considered priceless and excluded from cheapest-active resolution. There is no per-offer currency — the store decides.
x >= 0Where this offer row came from. Affects source_priority defaults used when reconciling conflicting rows for the same (product, store, sku). manual is the safe default for ad-hoc API writes; use the more specific value when you know it.
brand, affiliate_feed, scrape, pos_sync, manual, user_feedback Units physically on the shelf at last count. null when unknown — common for stores without a POS sync. Decremented as sales come in (POS sync) or set manually via update.
x >= 0Aisle/shelf locator for in-store wayfinding (e.g. A5, Dairy 12). Free-form and store-specific; we do not validate the format.
50true when the product can be reserved online and picked up at this store. Independent of status: an offer can be active on the shelf without supporting reservation.
Response
OK
An offer for a product at a specific physical store.
Mirrors :class:apps.retailers.models.InStoreOffer plus a structured price
that combines the row's bare decimal with the parent store's currency. One row
per (product, physical_store, sku) — that trio is the unique key.
URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$UUID of the catalog Product this offer is for. The product must already exist; create it via the products API before adding offers. Immutable after creation — moving a row to a different product means deleting and recreating.
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$UUID of the PhysicalStore (a single brick-and-mortar location, not the parent retailer chain) this offer lives at. The currency on the parent store is what price is denominated in — there is no per-offer currency override.
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$Developer-attached key/value data attached to this object. Up to 50 keys; key max 40 chars, value max 500 chars.
URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
22^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$Retailer-specific SKU for this product at this store. Empty string when the source doesn't expose a SKU (scraped offers often don't). Together with product_id and physical_store_id this is the row's natural key — the trio must be unique.
100Structured price: amount is the bare decimal stored on the row, currency is lifted from the parent store's currency field at read time. amount is null when the price is unknown — display 'Call for price' rather than $0.00.
{ "amount": "5.99", "currency": "USD" }Lifecycle state of this offer at this store. active is resolvable; out_of_stock, seasonal, and discontinued are filtered out of cheapest-active resolution. seasonal is a hint that the offer comes back; discontinued is permanent.
active, discontinued, seasonal, out_of_stock true when a human or trusted feed has confirmed this offer is real. Defaults to false for scraped or auto-ingested rows. The platform may surface verified offers preferentially in search but verification does not affect price resolution.
Where this offer row came from. Affects source_priority defaults used when reconciling conflicting rows for the same (product, store, sku). manual is the safe default for ad-hoc API writes; use the more specific value when you know it.
brand, affiliate_feed, scrape, pos_sync, manual, user_feedback Units physically on the shelf at last count. null when unknown — common for stores without a POS sync. Decremented as sales come in (POS sync) or set manually via update.
x >= 0Aisle/shelf locator for in-store wayfinding (e.g. A5, Dairy 12). Free-form and store-specific; we do not validate the format.
50true when the product can be reserved online and picked up at this store. Independent of status: an offer can be active on the shelf without supporting reservation.