Skip to main content
GET
/
retailers
/
api
/
v1
/
online-offers
/
{offer_id}
Get online offer
curl --request GET \
  --url https://www.closient.com/retailers/api/v1/online-offers/{offer_id} \
  --header 'X-API-Key: <api-key>'
{
  "id": "<string>",
  "product_id": "<string>",
  "online_store_id": "<string>",
  "metadata": {},
  "organization_id": "<string>",
  "sku": "",
  "url": "",
  "price": {
    "amount": "5.99",
    "currency": "USD"
  },
  "status": "active",
  "is_verified": false,
  "source": "manual",
  "fulfillment_type": "standard",
  "stock_level": "unknown",
  "delivery_countries": [
    "<string>"
  ],
  "shipping_cost": "<string>",
  "lead_time_days": 1,
  "min_order_quantity": 1
}

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

​
X-API-Key
string
header
required

Path Parameters

​
offer_id
string<shortuuid>
required

UUID of the online offer to retrieve.

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

Response

OK

An offer for a product on a specific online storefront.

Mirrors :class:apps.retailers.models.OnlineOffer plus a structured price that combines the row's bare decimal with the parent store's currency. One row per (product, online_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}$
​
online_store_id
string<shortuuid>
required

UUID of the OnlineStore (a single web storefront — amazon.com, wholefoodsmarket.com, etc., not the parent retailer entity) this offer lives on. The currency on the parent store is what price and shipping_cost are denominated in — there is no per-offer currency override.

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:""

Storefront-specific SKU (or ASIN, item ID, etc.) for this product on this site. Empty string when the source doesn't expose one. Together with product_id and online_store_id this is the row's natural key — the trio must be unique.

Maximum string length: 100
​
url
string
default:""

Deep link to the product page on the storefront. Should resolve to a buyable page; url_status reflects the most recent reachability check. Empty string when the source did not expose a URL (rare for online offers — usually means a feed-only row without a public PDP yet).

Maximum string length: 1000
​
price
PriceOut · object

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

Example:
{ "amount": "5.99", "currency": "USD" }
​
status
enum<string>
default:active

Lifecycle state of this offer on the storefront. active is resolvable; out_of_stock, seasonal, and discontinued are filtered out of cheapest-active resolution. status is independent of stock_level — an offer can be active with stock_level=low_stock.

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

true when a human or trusted feed has confirmed this offer is real. Defaults to false for scraped or auto-ingested rows.

​
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; affiliate_feed for partner-feed ingest.

Available options:
brand,
affiliate_feed,
scrape,
pos_sync,
manual,
user_feedback
​
fulfillment_type
enum<string>
default:standard

How the storefront delivers this offer to the buyer. standard is plain ground shipping; prime covers Amazon Prime / equivalent fast-shipping memberships; ship_to_store and store_pickup involve a brick-and-mortar leg even though the offer is online. Only meaningful for offers where url is buyable.

Available options:
standard,
same_day,
next_day,
prime,
ship_to_store,
store_pickup,
digital_download,
subscribe_and_save
​
stock_level
enum<string>
default:unknown

How much inventory is reported by the storefront. in_stock and low_stock are buyable now; pre_order and backordered are buyable but with a wait; out_of_stock is unbuyable; unknown is the safe default when the source doesn't surface stock signals.

Available options:
in_stock,
low_stock,
pre_order,
backordered,
out_of_stock,
unknown
​
delivery_countries
string[]

ISO 3166-1 alpha-2 country codes this offer ships to (e.g. ["US"], ["US", "CA"]). Empty list means inherit from storefront — the API does not infer a default. Codes must be uppercase 2-letter.

​
shipping_cost
string | null

Bare decimal shipping cost in the parent store's currency. null when free or unknown — distinguish via fulfillment_type (prime and similar imply free) or by the storefront's documented behaviour.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
​
lead_time_days
integer | null

Expected handling + shipping time in calendar days. null when unknown. Same-day and next-day fulfillment types ought to report 0 or 1; backordered offers may report higher values reflecting restock ETAs.

Required range: x >= 0
​
min_order_quantity
integer
default:1

Minimum number of units that must be purchased in a single order. Defaults to 1. Higher values are common for wholesale/B2B feeds.

Required range: x >= 1