Skip to main content
GET
Get in-store offer

Authorizations

X-API-Key
string
header
required

Path Parameters

offer_id
string<shortuuid>
required

UUID of the in-store offer to retrieve.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$

Response

OK

An offer for a product at a specific physical store.

Mirrors :class:apps.retailers.models.InStoreOffer, whose price stores its amount and ISO 4217 currency together. One row per (product, physical_store, sku) — that trio is the unique key.

id
string<shortuuid>
required

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

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
product_id
string<shortuuid>
required

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.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
physical_store_id
string<shortuuid>
required

UUID of the PhysicalStore (a single brick-and-mortar location, not the parent retailer chain) this offer lives at. The store's own currency seeds a new offer's denomination; the offer then carries it on its own row.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
metadata
Metadata · object

Developer-attached key/value data attached to this object. Up to 50 keys; key max 40 chars, value max 500 chars.

organization_id
string<shortuuid> | null

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

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
sku
string
default:""

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.

Maximum string length: 100
price
PriceOut · object

Structured price: amount and currency are stored together on the row and returned together. Both are null when the price is unknown — display 'Call for price' rather than $0.00, and never assume a denomination.

Example:
status
enum<string>
default:active

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.

Available options:
active,
discontinued,
seasonal,
out_of_stock
is_verified
boolean
default:false

true when Closient has confirmed this offer is real. Read-only: set only by Closient-controlled paths, never through this API. An offer submitted by an organization other than the product's owner is shown on public surfaces (product page, search, structured data) only when this is true.

source
enum<string>
default:manual

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.

Available options:
brand,
affiliate_feed,
scrape,
pos_sync,
manual,
user_feedback
quantity_on_hand
integer | null

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.

Required range: x >= 0
aisle
string
default:""

Aisle/shelf locator for in-store wayfinding (e.g. A5, Dairy 12). Free-form and store-specific; we do not validate the format.

Maximum string length: 50
store_pickup_available
boolean
default:false

true 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.