# Liquid Rewards API

## Docs

- [POST /chat/{convo_id} — Send a Shopper Message](https://docs.liquidrewardsapi.com/api-reference/chat/send-message.md): POST /chat/{convo_id} sends a message to the Liquid Rewards AI shopping assistant. Returns ranked products, refinement options, and pagination metadata.
- [GET /spy/{convo_id} — Inspect Conversation State](https://docs.liquidrewardsapi.com/api-reference/chat/spy-state.md): Retrieve the current state of any Liquid Rewards conversation session by convo_id. Useful for debugging chat context, product filters, and session history.
- [POST /v1/discovery/products/criteria-sets — Create Criteria Set](https://docs.liquidrewardsapi.com/api-reference/criteria-sets/create.md): POST /v1/discovery/products/criteria-sets creates a named criteria set. Accepts an ID, name, optional query, exclude_query, and array of filter criteria.
- [DELETE /v1/discovery/products/criteria-sets/{id} — Delete Criteria Set](https://docs.liquidrewardsapi.com/api-reference/criteria-sets/delete.md): DELETE /v1/discovery/products/criteria-sets/{id} permanently removes a criteria set from your account. Searches referencing this ID will stop applying its filters.
- [GET /v1/discovery/products/criteria-sets/{id} — Get Criteria Set](https://docs.liquidrewardsapi.com/api-reference/criteria-sets/get.md): GET /v1/discovery/products/criteria-sets/{id} retrieves a single saved criteria set. Returns its name, query, exclude_query, criteria array, and timestamps.
- [GET /v1/discovery/products/criteria-sets — List Criteria Sets](https://docs.liquidrewardsapi.com/api-reference/criteria-sets/list.md): GET /v1/discovery/products/criteria-sets lists all saved criteria sets for your account. Returns IDs, names, optional query filters, and criteria rules.
- [PUT /v1/discovery/products/criteria-sets/{id} — Upsert Criteria Set](https://docs.liquidrewardsapi.com/api-reference/criteria-sets/upsert.md): Create or update a saved affiliate discovery criteria set by ID. If the ID exists, it is replaced; otherwise a new set is created.
- [GET /v1/discovery/products/{slug} — Get Product Details](https://docs.liquidrewardsapi.com/api-reference/discovery/get-product.md): GET /v1/discovery/products/{slug} retrieves full affiliate product details. Returns pricing, merchant info, brand, category, and availability for one product.
- [GET /v1/discovery/merchants — List Affiliate Merchants](https://docs.liquidrewardsapi.com/api-reference/discovery/list-merchants.md): List all available affiliate merchants with pagination. Returns merchant details including name, domain, categories, and product counts.
- [GET /v1/discovery/merchants/search — Search Affiliate Merchants](https://docs.liquidrewardsapi.com/api-reference/discovery/search-merchants.md): GET /v1/discovery/merchants/search finds affiliate merchants by name. Returns name, domain, product count, affiliate networks, and categories for each match.
- [POST /v1/discovery/products/search — Search Affiliate Products](https://docs.liquidrewardsapi.com/api-reference/discovery/search-products.md): Search affiliate products with free-text queries and structured criteria filters. Returns paginated results with cursor-based navigation.
- [POST /clickthrough/{convo_id} — Record an Affiliate Click](https://docs.liquidrewardsapi.com/api-reference/events/clickthrough.md): POST /clickthrough/{convo_id} records an affiliate product click for loyalty program attribution. Accepts program, email, click_id, click_datetime, and presentation_id.
- [GET /clickthrough/{convo_id}/{presentment_id} — Clickthrough Redirect](https://docs.liquidrewardsapi.com/api-reference/events/clickthrough-redirect.md): Redirect a user through an affiliate tracking link. Pass click attribution details as query parameters for proper program attribution.
- [POST /signup/{convo_id} — Register a User Signup](https://docs.liquidrewardsapi.com/api-reference/events/register-signup.md): Register a user's loyalty program signup, linking it to a conversation session with optional UTM attribution and product context.
- [GET /inventory/ranking-sessions — Get Ranked Product Page](https://docs.liquidrewardsapi.com/api-reference/inventory/get-ranking-page.md): GET /inventory/ranking-sessions fetches a page of ranked affiliate products from an ongoing chat session. Requires conversation_id, session_id, and page_index.
- [POST /offers/carousel — Build a Carousel Affiliate Offer](https://docs.liquidrewardsapi.com/api-reference/offers/build-carousel.md): POST /offers/carousel builds an affiliate reward offer formatted for carousel display. Accepts an OfferMessage and returns an OfferReference or MessageAck.
- [POST /offers/multi — Build Multiple Affiliate Offers](https://docs.liquidrewardsapi.com/api-reference/offers/build-multi.md): POST /offers/multi batch-builds multiple affiliate reward offers in one request. Accepts an array of OfferMessage objects, returns an array of OfferReferences.
- [POST /offers/single — Build a Single Affiliate Offer](https://docs.liquidrewardsapi.com/api-reference/offers/build-single.md): POST /offers/single builds one affiliate reward offer from a ProductClick and ProductInfo. Returns an OfferReference ID or a MessageAck for async processing.
- [GET /offers/retry/{convo_id}/{presentment_id} — Retry an Offer](https://docs.liquidrewardsapi.com/api-reference/offers/retry.md): Retry a previously built affiliate offer for a given conversation and presentment ID. Pass click attribution details as query parameters.
- [Authenticate Requests to Liquid Rewards API](https://docs.liquidrewardsapi.com/authentication.md): Learn how to pass your API key in requests to the Liquid Rewards API and understand which endpoints require authentication.
- [Affiliate Discovery: Search Products and Merchants](https://docs.liquidrewardsapi.com/concepts/affiliate-discovery.md): Learn how Liquid Rewards affiliate discovery lets you search millions of affiliate products and browse merchant catalogs with rich filtering options.
- [Conversations: How Chat Sessions Work in Liquid Rewards](https://docs.liquidrewardsapi.com/concepts/conversations.md): Understand how conversation sessions work in the Liquid Rewards API, including convo_id, state management, and shopping assistant replies.
- [Criteria Filters: Structured Product Filtering](https://docs.liquidrewardsapi.com/concepts/criteria-filters.md): Use criteria filters and saved criteria sets in Liquid Rewards to apply structured product filters to affiliate discovery searches.
- [Offers: Reward Presentments in Liquid Rewards API](https://docs.liquidrewardsapi.com/concepts/offers.md): Learn how offers work in Liquid Rewards API — build single, multi, and carousel offers from product data and track them through the affiliate lifecycle.
- [Build Affiliate Reward Offers with Liquid Rewards API](https://docs.liquidrewardsapi.com/guides/building-offers.md): Build single, multi, and carousel affiliate reward offers using the Liquid Rewards offers API. Covers the OfferMessage schema, response types, and retry flow.
- [Integrate the Liquid Rewards AI Chat Shopping Assistant](https://docs.liquidrewardsapi.com/guides/chat-integration.md): Step-by-step guide to embedding the Liquid Rewards AI shopping assistant. Covers messages, refinements, price filters, and inventory pagination.
- [Track Affiliate Clicks with Liquid Rewards Clickthrough API](https://docs.liquidrewardsapi.com/guides/click-tracking.md): Record affiliate product clicks and redirect users through affiliate links using the Liquid Rewards clickthrough API.
- [Search Affiliate Products with Liquid Rewards Discovery](https://docs.liquidrewardsapi.com/guides/product-search.md): Learn how to search affiliate products using free-text queries, structured criteria, and cursor-based pagination in Liquid Rewards.
- [Register User Signups with Liquid Rewards API](https://docs.liquidrewardsapi.com/guides/signup-registration.md): Register user signups and link them to loyalty program sessions in Liquid Rewards. Covers UTM attribution, card-linked offers, and product context.
- [Liquid Rewards API: AI Shopping & Affiliate Rewards](https://docs.liquidrewardsapi.com/introduction.md): Liquid Rewards API powers conversational product discovery, affiliate offer building, and click tracking for loyalty and rewards programs.
- [Get Started with Liquid Rewards API](https://docs.liquidrewardsapi.com/quickstart.md): Make your first Liquid Rewards API call in minutes. Search affiliate products, paginate results, and retrieve full product details in four steps.