The Offers API lets you register affiliate product presentments as reward offers in your loyalty program. You can build individual offers, batch multiple offers in one request, or create carousel-style offer experiences.
The offers endpoints do not require an API key. Include all required product_click fields — program, email, convo_id, presentation_id, click_id, and click_datetime — to ensure proper attribution.
The OfferMessage Structure
Every offer is built from an OfferMessage containing a ProductClick (who clicked what) and ProductInfo (the product details):
{
"product_click": {
"program": "my-loyalty-program",
"email": "user@example.com",
"convo_id": "session-abc123",
"presentation_id": "pres-001",
"click_id": "click-001",
"click_datetime": "2024-01-15T10:30:00Z"
},
"product_info": {
"name": "Nike Air Zoom Pegasus 41",
"direct_link": "https://affiliate.net/track?id=001",
"detail_link": "https://nike.com/products/pegasus",
"image_url": "https://cdn.example.com/pegasus.jpg",
"value": 120.00,
"price": "$120.00",
"description": "Lightweight running shoe for marathon training",
"rebate_pct": 5.0,
"presentment_id": "pres-001",
"merchant": { "id": 1, "name": "Nike" },
"brand": "Nike",
"category": "Athletic Footwear",
"currency": "USD",
"on_sale": false
}
}
ProductClick Fields
Your loyalty program identifier.
The user’s email address.
The conversation/session ID generated at the start of the user’s chat session.
The ID of the offer presentment shown to the user.
A unique identifier for this click event.
ISO 8601 timestamp of when the click occurred (e.g., "2024-01-15T10:30:00Z").
ProductInfo Fields
Display name of the product.
The affiliate tracking URL users are redirected to on click.
The canonical product page URL on the merchant’s site.
URL of the product image for display in the offer UI.
Numeric product price used for reward calculations.
Human-readable formatted price string (e.g., "$120.00").
Short product description shown in the offer card.
Affiliate rebate percentage to be awarded to the user upon purchase.
Must match the presentation_id in the accompanying ProductClick.
Object containing id (integer) and name (string) for the affiliate merchant.
Brand name of the product.
Product category (e.g., "Athletic Footwear").
ISO 4217 currency code (e.g., "USD").
Whether the product is currently on sale.
Building a Single Offer
POST a single OfferMessage to /offers/single. Returns an OfferReference with the offer’s integer ID, or a MessageAck for async processing.
curl -X POST https://rewardsbot-prod.liquidrewardsapi.com/offers/single \
-H "Content-Type: application/json" \
-d '{
"product_click": {
"program": "my-loyalty-program",
"email": "user@example.com",
"convo_id": "session-abc123",
"presentation_id": "pres-001",
"click_id": "click-001",
"click_datetime": "2024-01-15T10:30:00Z"
},
"product_info": {
"name": "Nike Air Zoom Pegasus 41",
"direct_link": "https://affiliate.net/track?id=001",
"value": 120.00,
"price": "$120.00",
"rebate_pct": 5.0,
"presentment_id": "pres-001",
"currency": "USD",
"on_sale": false
}
}'
Building Multiple Offers
Send an array of OfferMessage objects to /offers/multi to build multiple offers in a single request. Returns an array of OfferReference objects.
curl -X POST https://rewardsbot-prod.liquidrewardsapi.com/offers/multi \
-H "Content-Type: application/json" \
-d '[
{
"product_click": { "program": "my-loyalty-program", "email": "user@example.com", "convo_id": "session-abc123", "presentation_id": "pres-001", "click_id": "click-001", "click_datetime": "2024-01-15T10:30:00Z" },
"product_info": { "name": "Nike Air Zoom Pegasus 41", "direct_link": "https://affiliate.net/track?id=001", "value": 120.00, "price": "$120.00", "rebate_pct": 5.0, "presentment_id": "pres-001", "currency": "USD", "on_sale": false }
},
{
"product_click": { "program": "my-loyalty-program", "email": "user@example.com", "convo_id": "session-abc123", "presentation_id": "pres-002", "click_id": "click-002", "click_datetime": "2024-01-15T10:31:00Z" },
"product_info": { "name": "Adidas Ultraboost 24", "direct_link": "https://affiliate.net/track?id=002", "value": 190.00, "price": "$190.00", "rebate_pct": 4.5, "presentment_id": "pres-002", "currency": "USD", "on_sale": true }
}
]'
Building Carousel Offers
The carousel endpoint formats the offer for display in a product carousel UI. POST a single OfferMessage to /offers/carousel:
curl -X POST https://rewardsbot-prod.liquidrewardsapi.com/offers/carousel \
-H "Content-Type: application/json" \
-d '{
"product_click": {
"program": "my-loyalty-program",
"email": "user@example.com",
"convo_id": "session-abc123",
"presentation_id": "pres-001",
"click_id": "click-001",
"click_datetime": "2024-01-15T10:30:00Z"
},
"product_info": {
"name": "Nike Air Zoom Pegasus 41",
"direct_link": "https://affiliate.net/track?id=001",
"image_url": "https://cdn.example.com/pegasus.jpg",
"value": 120.00,
"price": "$120.00",
"rebate_pct": 5.0,
"presentment_id": "pres-001",
"currency": "USD",
"on_sale": false
}
}'
Retrying Failed Offers
If an offer presentation fails or needs to be retried, use the retry endpoint with the session and presentment identifiers:
curl "https://rewardsbot-prod.liquidrewardsapi.com/offers/retry/SESSION_ID/PRESENTMENT_ID?email=user@example.com&program=my-loyalty-program&click_id=click-001&click_datetime=2024-01-15T10%3A30%3A00Z"
| Query Parameter | Description |
|---|
email | User’s email address |
program | Loyalty program identifier |
click_id | The original click ID to retry |
click_datetime | ISO 8601 timestamp of the original click event |
