Skip to main content
PUT
/
retailers
/
api
/
v1
/
online-offers
/
{offer_id}
Update online offer
curl --request PUT \
  --url https://www.closient.com/retailers/api/v1/online-offers/{offer_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "metadata": {},
  "sku": "<string>",
  "url": "<string>",
  "price": 1,
  "status": "active",
  "source": "brand",
  "fulfillment_type": "standard",
  "stock_level": "in_stock",
  "delivery_countries": [
    "<string>"
  ],
  "shipping_cost": 1,
  "lead_time_days": 1,
  "min_order_quantity": 2
}
'
{
  "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 update.

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

Body

application/json

Partial update payload for an online offer.

Every field is optional. Omitted keys preserve existing values (PATCH semantics on a PUT endpoint, kept for backward compatibility). product_id and online_store_id are not updatable — delete and recreate to move a row.

​
metadata
Metadata · object

Developer-attached key/value data. Send {} or null to clear. Empty-string values delete that key. Omitted keys are preserved.

​
sku
string | null

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 | null

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

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

Required range: x >= 0
​
status
enum<string> | null

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
​
source
enum<string> | null

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> | null

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> | null

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[] | null

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

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.

Required range: x >= 0
​
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 | null

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

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