Skip to main content
The Liquid Rewards chat API lets you embed an AI shopping assistant into your platform. Users describe what they’re looking for in natural language, and the assistant returns ranked product results, refinement options, and pagination metadata.
1

Create a Conversation ID

Generate a unique convo_id for each user session. This ID ties together all chat messages, clickthroughs, and signups for that session.
const convoId = crypto.randomUUID(); // e.g., "a1b2c3d4-e5f6-..."
2

Send the First Message

POST to /chat/{convo_id} with the user’s message. No API key is required for the chat endpoint.
curl -X POST https://rewardsbot-prod.liquidrewardsapi.com/chat/a1b2c3d4 \
  -H "Content-Type: application/json" \
  -d '{"chat": "I need running shoes for a marathon"}'
3

Display the Response

Parse the ShopperReply. Show the agent_reply text to the user. Render products from found_products.search_results. Show refinement_result.options as clickable filter chips.
const reply = await response.json();

// Display assistant message
console.log(reply.agent_reply);

// Show products
const products = Object.values(reply.found_products?.search_results ?? {}).flat();
products.forEach(p => console.log(p.name, p.price));

// Show refinement options
if (reply.refinement_result?.options) {
  const { category, options } = reply.refinement_result;
  console.log(`Refine by ${category}:`, options);
}
4

Handle Refinements

When a user clicks a refinement option, send a follow-up message with refinement_selection:
const followUp = await fetch(`https://rewardsbot-prod.liquidrewardsapi.com/chat/${convoId}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    refinement_selection: { category: 'brand', selection: 'Nike' }
  })
});
5

Handle Pagination

If pagination.has_next_page is true, fetch the next page using the session identifiers returned in the response:
if (reply.pagination?.has_next_page) {
  const { conversation_id, session_id, next_page_index } = reply.pagination;
  const nextPage = await fetch(
    `https://rewardsbot-prod.liquidrewardsapi.com/inventory/ranking-sessions/${conversation_id}/${session_id}/pages/${next_page_index}`
  );
}
6

Apply Price Filters

Users can filter results by price range. POST a product_filter object with low_price and high_price bounds:
const filtered = await fetch(`https://rewardsbot-prod.liquidrewardsapi.com/chat/${convoId}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    product_filter: { low_price: 50, high_price: 150 }
  })
});
Combine chat, refinement_selection, and product_filter in the same request to give users fine-grained control over their shopping experience.