Skip to main content
Offers are the central mechanism for presenting affiliate products to users as rewards. When a user sees a product recommendation and you want to record that presentment — and potentially track it through to a click or purchase — you build an offer. An offer wraps a product with affiliate tracking data and produces a reference ID for later use throughout the affiliate lifecycle.

​
What is an Offer?

An offer links two key pieces of information:
  • A ProductClick — the click event metadata identifying who saw the product, when, and in what context.
  • ProductInfo — the product details shown to the user, including pricing, imagery, and affiliate link.
When you build an offer, the API returns an OfferReference containing an integer id. This ID tracks the presentment in the system and is used to associate downstream events (clicks, signups, conversions) with the original product display.
Offer IDs are integers assigned by the Liquid Rewards system. Store the OfferReference.id returned from each build call — you will need it when recording subsequent affiliate events.

​
Offer Types

Liquid Rewards provides three offer endpoint variants depending on your display format:

Single Offer

POST /offers/singleBuild one offer from a single product. Use this for inline product recommendations or one-at-a-time displays.

Multi Offer

POST /offers/multiBatch-build multiple offers in a single request. Use this when rendering a product grid or list to minimize round-trips.

Carousel Offer

POST /offers/carouselBuild one offer formatted for carousel display. Use this for horizontal scrolling product widgets.

​
The OfferMessage Schema

All three offer endpoints accept an OfferMessage request body with the same structure. 
POST https://rewardsbot-prod.liquidrewardsapi.com/offers/single
Content-Type: application/json

{
  "product_click": {
    "program": "loyalty-program-id",
    "email": "user@example.com",
    "convo_id": "sess-abc123",
    "presentation_id": "pres-xyz",
    "click_id": "click-001",
    "click_datetime": "2024-01-15T10:30:00Z"
  },
  "product_info": {
    "name": "Nike Air Zoom Pegasus 41",
    "direct_link": "https://affiliate.example.com/track?id=001",
    "detail_link": "https://nike.com/products/pegasus",
    "image_url": "https://example.com/pegasus.jpg",
    "value": 120.00,
    "price": "$120.00",
    "description": "Lightweight running shoe",
    "rebate_pct": 5.0,
    "presentment_id": "pres-xyz",
    "merchant": { "id": 1, "name": "Nike" }
  }
}

​
product_click fields

​
product_click.program
string
required
The loyalty program identifier associated with this presentment. Determines which reward program the user earns under.
​
product_click.email
string
required
The email address of the user being shown the offer. Used for reward attribution.
​
product_click.convo_id
string
required
The conversation ID for the current session. Must match the convo_id used in chat and other session events. See Conversations for details.
​
product_click.presentation_id
string
required
A unique identifier for this specific product presentment. Used to correlate the offer build with subsequent click and conversion events.
​
product_click.click_id
string
required
An identifier for the click event. Can be a UUID or any unique string you generate per click.
​
product_click.click_datetime
string
required
ISO 8601 timestamp for when the product was presented or clicked. Example: 2024-01-15T10:30:00Z.

​
product_info fields

​
product_info.name
string
required
The display name of the product shown to the user.
​
product_info.direct_link
string
required
The affiliate-tracked URL the user will be sent to upon clicking the product. This link includes affiliate tracking parameters.
​
product_info.detail_link
string
A canonical product page URL (non-affiliate). Used for display or metadata purposes.
​
product_info.image_url
string
URL of the product image to display in the offer UI.
​
product_info.value
number
The numeric product value (regular retail price) used for reward calculation.
​
product_info.price
string
The formatted display price shown to the user (e.g., "$120.00").
​
product_info.description
string
A short product description displayed in the offer card.
​
product_info.rebate_pct
number
The cashback or rebate percentage the user earns for purchasing this product. Displayed as a reward incentive.
​
product_info.presentment_id
string
required
Must match product_click.presentation_id. Links the product display record to the click event record.
​
product_info.merchant
object
The merchant associated with this product.

​
Offer Response

A successful offer build returns one of two response shapes depending on whether the API processed the request synchronously or asynchronously.

​
Synchronous: OfferReference

{ "id": 42 }
​
id
integer
The system-assigned integer ID for this offer presentment. Store this value — it is used to reference the offer in downstream events.

​
Asynchronous: MessageAck

{
  "message_type": "offer_ack",
  "message_id": "msg-001",
  "target": "offers",
  "data": {}
}
​
message_type
string
Identifies the acknowledgement type. Will be "offer_ack" for offer builds.
​
message_id
string
A unique identifier for the async message. Use this for tracing if you need to follow up with support.
​
target
string
The system target that received the message (e.g., "offers").
​
data
object
Additional response payload. May be empty ({}) for basic acknowledgements.
When you receive a MessageAck instead of an OfferReference, the offer has been queued for processing. The OfferReference.id will be available after processing completes. Design your integration to handle both response shapes.

​
Retrying Offers

If an offer needs to be re-presented to a user — for example, after a session resume or a failed initial display — use the retry endpoint to regenerate the offer without creating a duplicate record. 
GET https://rewardsbot-prod.liquidrewardsapi.com/offers/retry/{convo_id}/{presentment_id}

​
Path Parameters

​
convo_id
string
required
The conversation ID for the session in which the offer was originally built.
​
presentment_id
string
required
The presentation_id used when the offer was originally built.

​
Query Parameters

​
email
string
required
The email address of the user associated with the offer.
​
program
string
required
The loyalty program identifier used in the original offer.
​
click_id
string
required
The click ID from the original offer’s product_click.
​
click_datetime
string
required
The original click timestamp in ISO 8601 format.

​
Example

GET https://rewardsbot-prod.liquidrewardsapi.com/offers/retry/sess-abc123/pres-xyz \
  ?email=user@example.com \
  &program=loyalty-program-id \
  &click_id=click-001 \
  &click_datetime=2024-01-15T10:30:00Z
Always use the same click_id and click_datetime as the original offer when retrying. Changing these values will create mismatched records in the affiliate tracking system.