Skip to main content
The signup registration endpoint lets you record when users join or register for a rewards program during a shopping session. This ties the signup event to the conversation and product context, enabling accurate attribution for your loyalty program.

​
Registering a Signup

POST to /signup/{convo_id} with the user’s details. Returns HTTP 202 Accepted — the signup is processed asynchronously. 
curl -X POST https://rewardsbot-prod.liquidrewardsapi.com/signup/SESSION_ID \
  -H "Content-Type: application/json" \
  -d '{
    "program":         "my-loyalty-program",
    "email":           "user@example.com",
    "presentation_id": "pres-001",
    "card_bin":        "411111",
    "external_id":     "user-12345",
    "utm": {
      "utm_source":   "email",
      "utm_medium":   "newsletter",
      "utm_campaign": "summer-launch"
    }
  }'

​
Request Fields

​
convo_id
string
required
The conversation/session ID. Ties the signup event to the current shopping session for attribution.
​
program
string
required
Your loyalty program identifier.
​
email
string
required
The user’s email address.
​
presentation_id
string
The offer presentment ID associated with this signup, if the user registered in the context of a specific offer.
​
card_bin
string
First 6 digits of the user’s payment card BIN. Required for card-linked offer programs that match transactions to cardholders.
​
external_id
string
Your internal user identifier for cross-referencing signups against your own user database.
​
utm
object
UTM attribution parameters as key-value pairs. Pass any standard UTM keys (utm_source, utm_medium, utm_campaign, utm_content, utm_term) to track which campaigns drove signups.
​
product_info
object
The ProductInfo object for the product associated with this signup event. Useful when the signup was triggered by a specific product offer.

​
Response

A successful signup request returns HTTP 202 Accepted. The body contains a MessageAck confirming the event was received and queued for processing. No synchronous confirmation of the signup record is returned — use your external_id to reconcile later.

​
UTM Attribution

Pass UTM parameters to track which campaigns and channels drove signups into your loyalty program: 
{
  "program": "cashback-program",
  "email":   "user@example.com",
  "utm": {
    "utm_source":   "google",
    "utm_medium":   "cpc",
    "utm_campaign": "q1-acquisition",
    "utm_content":  "banner-ad"
  }
}
Use external_id to link Liquid Rewards signups to your own user database for reconciliation and reporting.

​
Card-Linked Offers

If your program supports card-linked offers, include the card_bin field to enable transaction matching for the enrolled cardholder: 
{
  "program":     "card-rewards",
  "email":       "cardholder@example.com",
  "card_bin":    "411111",
  "external_id": "cardholder-uuid"
}
The card_bin is the first 6 digits of the card number only. Never send full card numbers or other sensitive PAN data to the Liquid Rewards API.

​
Signup with Product Context

When a user signs up in direct response to a product offer, include both presentation_id and product_info to capture the full attribution chain: 
{
  "program":         "my-loyalty-program",
  "email":           "user@example.com",
  "presentation_id": "pres-001",
  "external_id":     "user-12345",
  "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",
    "merchant":       { "id": 1, "name": "Nike" },
    "brand":          "Nike",
    "category":       "Athletic Footwear",
    "currency":       "USD",
    "on_sale":        false
  }
}