Skip to main content
GET
/
retailers
/
api
/
v1
/
in-store-offers
/
{offer_id}
/
promotions
List in-store offer promotions
curl --request GET \
  --url https://www.closient.com/retailers/api/v1/in-store-offers/{offer_id}/promotions \
  --header 'X-API-Key: <api-key>'
[
  {
    "id": "<string>",
    "short_id": "<string>",
    "offer_id": "<string>",
    "promotional_price": "<string>",
    "start_date": "2023-11-07T05:31:56Z",
    "end_date": "2023-11-07T05:31:56Z",
    "metadata": {},
    "currency": "",
    "promotion_type": "SALE",
    "description": "",
    "is_active": true
  }
]

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 in-store offer whose promotions to list.

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

Response

OK

​
id
string<shortuuid>
required

Stable UUID primary key of the promotion. Use this for cross-references.

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

URL-safe shortuuid (base57) encoding of id. Up to 22 characters; preferred over id in human-shareable URLs and log lines.

Maximum string length: 22
​
offer_id
string<shortuuid>
required

UUID of the parent InStoreOffer this promotion applies to. The offer must already exist; create it via the in-store offers API before attaching promotions. Immutable after creation — moving a promotion to a different offer means deleting and recreating.

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

Time-windowed override for the offer's regular price in the parent store's currency. Must be non-negative. When multiple promotions overlap on the same offer the cheapest active one wins; $0 is allowed and intentional for free-with-purchase BOGO arms (it is not a sentinel for 'unknown').

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
​
start_date
string<date-time>
required

Timestamp at which this promotion becomes effective (inclusive). Must be strictly before end_date — the database enforces end_date > start_date.

​
end_date
string<date-time>
required

Timestamp at which this promotion stops being effective (inclusive). A daily Celery beat task flips is_active to false once this passes; the row is kept for historical pricing rather than deleted.

​
metadata
Metadata · object

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

​
currency
string
default:""

ISO 4217 currency code lifted from the parent PhysicalStore.currency at read time. Read-only here — there is no per-promotion currency override; the store decides.

Maximum string length: 3
​
promotion_type
enum<string>
default:SALE

Merchandising context — display-only, does not change resolution semantics. Use SEASONAL for time-of-year promotions (Black Friday, holiday), CLEARANCE for end-of-life inventory, BOGO for buy-one-get-one arms (often at promotional_price=0), BUNDLE for discounts that apply when buying with another product, INTRODUCTORY for launch pricing, LOYALTY for member-only prices, and SALE (the default) for everything else.

Available options:
SALE,
CLEARANCE,
BOGO,
BUNDLE,
SEASONAL,
INTRODUCTORY,
LOYALTY
​
description
string
default:""

Optional human-readable label shown alongside the promoted price (e.g. 'Black Friday weekend', 'Member appreciation week'). Free-form, up to 255 characters. Empty string when no label is needed.

Maximum string length: 255
​
is_active
boolean
default:true

Soft-deactivate flag. true means the promotion is eligible for cheapest-active resolution within its date window; false excludes it (the daily beat task auto-flips this to false once end_date passes). Use the update endpoint to set this to false rather than deleting if you want to preserve the historical pricing row.