Offers
Create, retrieve, update, delete, and list targeted promotional offers.
An offer is a targeted promotion — such as buy-one-get-one, free shipping, or a fixed discount — that activates when a customer's order meets defined qualifying criteria. Unlike coupons, offers are applied automatically when criteria are satisfied rather than requiring a code.
Illustrative content. Hand-authored to demonstrate the Standard/Advanced pattern; the production page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.
The offer objectAsk
idstringUnique identifier for the offer, e.g. ofr_3Fj7tN.
namestringHuman-readable name for the offer, e.g. Free Shipping on Orders Over $50.
typeenumOne of bogo (buy-one-get-one), free_shipping, or fixed_discount.
valueintegerThe value of the promotion in the smallest currency unit — the discount amount for
fixed_discount, the shipping credit for free_shipping, or null for bogo.
criteriaobjectQualifying conditions that must be met for the offer to apply.
activebooleantrue if the offer is currently live and will be evaluated at checkout.
starts_atintegerUnix timestamp when the offer becomes active.
ends_atintegerUnix timestamp when the offer expires. null if open-ended.
createdintegerUnix timestamp when this offer was created.
Create an offerAsk
Define the offer type, value, and qualifying criteria. Offers become active immediately unless a
future starts_at is provided.
Retrieve an offerAsk
Fetch an offer by its ID.
Update an offerAsk
Toggle the offer active state or extend the end date. type, value, and criteria are immutable
after creation.
| Parameter | Type | Description |
|---|---|---|
active | boolean | Set to false to immediately deactivate the offer. |
ends_at | integer | New Unix timestamp for the offer expiry. |
Delete an offerAsk
Permanently deletes an offer. It will no longer be evaluated at checkout.
List offersAsk
Returns a paginated list of offers. Filter by active to show only live promotions.
| Parameter | Type | Description |
|---|---|---|
active | boolean | Return only active (true) or inactive (false) offers. |
limit | integer | Number of results to return. Default 10, max 100. |
Related eventsAsk
offer.created, offer.updated, and offer.ended. See Events.
