Paywall event reference

A server is private software that handles app requests. A paywall event is a request from that server after a person leaves your paywall. It gives Hyzl the facts that it needs for recovery. Start with Send the paywall event for a short setup guide. You can also use an AI code assistant.

Address

POST https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event
Authorization: Bearer <your server key>
Content-Type: application/json

Protect the ingest token

The ingest token is the secret that permits your server to send paywall events. On the Install page, this appears as Server key.

Select Copy setup guide on the Install page.
Store the guide’s key from your clipboard.
Store it as HYZL_INGEST_TOKEN in your server environment.
Use your platform’s secret command to read the clipboard.

On macOS, use $(pbpaste). On Windows, use Get-Clipboard -Raw. On Linux, use xclip -selection clipboard -o. Do not put this key in a chat, code file, test, log, or screenshot. Anyone with the key can send events for your app and use your Hyzl number. Copying the guide again returns the same key. It does not rotate it. If the key becomes visible, rotate it explicitly. A rotated key replaces the old key at once.

Choose the right moment

Send the event after a signed-in person sees your price and leaves without payment. This moment starts recovery.

Where	Fit	Why
The paywall is shown and they leave without buying	Recommended	They saw your price and did not buy. Recovery fits this moment.
The paywall appears	Good	The Flow wait gives the person time to finish payment.
Signup completes	Too early	The person did not see your price yet.
A phone number is collected, before the paywall	Too early	Same problem, one step sooner.

If you collect the phone number later, send another event with the same userId. The event with the phone number and consent starts the wait.

Fields

Field	Requirement	What happens without it
`userId` or `stripeCustomerId`	Required (one of them)	`400 missing_durable_id`. Email and phone alone cannot verify a payment, so we reject the event rather than risk texting someone who already paid. `userId` must be the same id your app passes to `Purchases.logIn()`. A `stripeCustomerId` must start with `cus_`. Minimum 5 characters.
`phoneNumber`	Required by the final step. May arrive on a later event.	Nobody can be contacted. The person is stored and shown as waiting for a phone number. E.164, e.g. `+13105551212`.
`consent.attested`	Required. Send the real state of whatever you collect, including `false`.	Absent leaves whatever we already hold for this person unchanged. An explicit `false` REVOKES consent: outreach stops immediately. Hyzl also keeps an explicit `false` for support conversations, even when it has no person for that user yet. The response does not change. A non-boolean is `400 invalid_consent`.
`consent.text`	Optional	The exact wording you showed. Stored with the person as your TCPA evidence trail.
`consent.at`	Optional	When they ticked it. ISO 8601.
`consent.voice`	Optional. `{ attested, text, at }`, with `attested` a Boolean.	Send it when you collect consent to calls apart from consent to texts. Hyzl calls only people whose `consent.voice.attested` is `true`, and still needs `consent.attested` to contact them at all. Absent means your app has one combined consent, so `consent.attested` covers calls too. A non-object or a non-Boolean `attested` is `400 invalid_consent`.
`optedOut`	Optional · boolean	`true` records a permanent STOP for this app and phone. Send `userId` or `stripeCustomerId`, a valid E.164 `phoneNumber`, `consent.attested: false`, and `consent.voice.attested: false`. A checkbox withdrawal remains reversible and needs no `optedOut`. Omitting `optedOut` or sending `false` does not clear a stored STOP.
`email`	Optional	A positive-only finder. A match resolves a Stripe customer for us to check; email never keys the person, because it is reassigned and is not unique in Stripe. Send it exactly as it is stored on your side — Stripe matches customer email case-sensitively, so we query both your spelling and its lowercase form.
`firstName`	Optional	The text uses “there” instead of their name. Never used to match people.
`eventId`	Optional	Send one to make retries safe. A repeat returns `200` without reprocessing event details; `optedOut: true` still records STOP and withdraws contact.
`occurredAt`	Optional	The wait is measured from when we receive the event instead of when it happened. ISO 8601 or epoch milliseconds.
`startTimerAt`	Optional	A later moment when the timer must start. Hyzl uses the later of `occurredAt` and `startTimerAt`. Re-sending it resets the timer.
`stage`	Optional	The text uses generic wording. `saw_value`, `saw_price` and `pre_offer` tailor it; any other label passes through as context.
`price`, `currency`	Optional	`{price}` renders blank and the phrase around it is dropped.
`recoveryUrl`	Optional	Your own https link, texted verbatim. We never read, change or add anything to it. A later value replaces an earlier one. Not https, or with embedded credentials, or over 2048 characters: `400 invalid_recovery_url`. Mark what this link creates in Stripe so its payments count as recovered — see Mark the payments Hyzl recovered.
`percentOff`	Optional	Your win-back percent, a whole number 1–90. Outside that: `400 invalid_percent_off`.
`offerLinks`	Optional	For Auto mode: the discount tiers your checkout can honour for this person, as whole percents 0–90 mapped to your own https links, e.g. `{"0": "https://…/full", "33": "https://…/33", "66": "https://…/66"}`. `"0"` is full price. Hyzl may move the person to one of these tiers (never above your app’s offer, never below what they already hold) and then texts that tier’s link. A tier above your app’s offer is dropped when it arrives. If `recoveryUrl` is one of the dropped tiers’ links, Hyzl uses your highest remaining tier’s link instead, so lowering your offer takes effect for everyone at once. Each link follows the `recoveryUrl` rules. A later event with `offerLinks` replaces them. Not an object, a key that is not a whole percent 0–90, or a bad link: `400 invalid_offer_links`.
`offers`	Optional	Your own plans for this person, for example the plans of the price test group they are in. A list of 1 to 4 plans, each with a `name`, a `price`, a `url` and a `use`. Exactly one plan has `"use": "lead"`, and the rest have `"use": "fallback"`. For this person, `offers` replaces `offerLinks`, `percentOff` and your app’s offer: Hyzl offers only these plans, and never a percent off. A later event with `offers` replaces them, and an event without it leaves them as they are. Anything else: `400 invalid_offers`. See Give Hyzl named offers.
`context`	Optional	A short string of facts about this person that helps the AI rep, e.g. their onboarding answers (“Goal: run a 10K. Blocker: price.”). Trimmed; up to 1000 characters. Given to the AI rep on texts and calls as information about the person, never as instructions, so send facts rather than directions. A later event with `context` replaces it. Not a string, or over 1000 characters: `400 invalid_context`.
`detail`	Optional	A short line for your message templates, used as `{detail}` in Flow texts, e.g. the trip they searched (“LA → Tokyo, business class, November”). Trimmed; up to 80 characters; no links. The AI rep also sees it as a fact about the person. In Auto mode the rep’s first text can name it as you wrote it, with an arrow read as “to” and a long one cut back at its commas. A later event with `detail` replaces it. Not a string, over 80 characters, or containing a link: `400 invalid_detail`.
`search`	Optional	What the person’s search in your app found before the paywall, so the AI rep can tell them. Economy results only. A `search` with the wrong shape is left out, and the event is still accepted. See Send the search the person ran.
`test`	Optional	For trying the flow, not for real signups. `true` texts the number on this event within a minute, skipping the wait, the paid check and your app’s on/off switch. It must include `phoneNumber` on the same event (`400 test_requires_phone`) and it never falls back to a number we already hold — otherwise a test against an existing record would text a real customer. Send a number you control. Never send `true` on a real signup.

Hyzl ignores fields that do not appear in this table.

Match each person to a payment

For RevenueCat, userId must equal the value that your app gives to Purchases.logIn(). The wrong value can make a person appear unpaid after a purchase. For Stripe, send stripeCustomerId when you know it. Also set client_reference_id or metadata.userId on the Checkout Session or Payment Link. Use the same userId in the paywall event. Hyzl checks each available Stripe identifier before contact. If a Stripe check fails, Hyzl waits instead of treating the person as unpaid. If people pay on your website through Stripe and in your iPhone app through RevenueCat, connect both. Send one userId for each person, the same value that your iPhone app passes to Purchases.logIn(). Set that same value as client_reference_id or metadata.userId on your Stripe Checkout. Hyzl then asks Stripe and RevenueCat before every step, and a payment that either one finds ends recovery. Someone who signed up in your iPhone app may have no Stripe customer. Hyzl contacts that person only when RevenueCat answers that they have not paid and Stripe finds no payment. Without a stripeCustomerId, Hyzl finds a web payment in only three ways. The first is a Checkout that carries the userId and started no earlier than a day before this event. The second is a subscription whose metadata.userId is the userId, or whose Stripe customer has that metadata.userId. Stripe can take about a minute to make a new one findable. The third is a subscription whose Stripe customer has this event’s email, written the same way or in all lowercase letters. So a one-time web payment is found only through the first way. Hyzl misses any other web payment by that person and can contact them. That includes an older Checkout that carried the userId only on the Checkout. For subscriptions, send stripeCustomerId whenever you know it, and set subscription_data.metadata.userId on the Checkout so that the subscription carries the userId. Hyzl also asks both before it texts your link to someone who writes back or calls. That applies only to people Hyzl has not already found paid. Someone Hyzl already found paid gets the link if they ask for it, without a new check, as before. If either check fails, Hyzl waits and does not contact the person. A RevenueCat failure is retried, even when RevenueCat refuses the connection. After eight failed checks in a row, about 25 hours after the first, recovery ends for that person. When Stripe refuses the connection (a 401 or 403 error), recovery ends sooner, about five minutes after the first failed check. Reconnect as soon as a card shows Connection broken. See Read the connection status. Without a userId, RevenueCat cannot find the person, so Hyzl never contacts them. This holds even when the event has a stripeCustomerId. Once you connect RevenueCat, send the Purchases.logIn() value as userId for every person.

Mark the payments Hyzl recovered

Hyzl can see that a person paid after it reached them. It cannot see why they paid. If you also run your own win-back emails, texts or checkout, those payments look identical. So Hyzl counts a payment as recovered revenue only when the Stripe object your checkout creates from recoveryUrl is marked as coming from Hyzl. Set either of these on the Checkout Session, Subscription or Invoice:

Metadata	Value	Notes
`source`	`hyzl`	Exactly that value. Case and surrounding spaces are ignored. Use this when one Hyzl link covers everything.
`campaign`	begins with `hyzl`	For example `hyzl_66` or `hyzl_annual`. Use this to tell several Hyzl offers apart; the rest of the value is yours.

Stripe copies subscription_data.metadata onto the Subscription rather than onto the invoices it raises. Hyzl follows that link for you, so marking the subscription is enough. If you send offers, mark the Stripe object behind each plan’s link: the lead and every fallback. client_reference_id is not attribution. It is how Hyzl finds the payment at all; keep sending it. Payments without a mark are not lost. People who pay after Hyzl reaches them are reported on Home and in Analytics as a separate count, and never as recovered revenue. RevenueCat purchases are always in that count: an App Store or Play Store transaction has no metadata for you to mark.

Give Hyzl a link for each offer

Use offerLinks if your checkout has a different secure link for each allowed discount. Each key is a whole discount percent from 0 through 90. The 0 key means the regular price.

{
  "offerLinks": {
    "0": "https://example.com/checkout/full-price",
    "25": "https://example.com/checkout/25-off",
    "50": "https://example.com/checkout/50-off"
  }
}

Hyzl uses only the links that you send for that person. Each link must follow the same rules as recoveryUrl.

Give Hyzl named offers

Use offers when a person must see your own plans, at your own prices. For example, a price test shows each person the prices of one test group. Send that person the plans of their group, and Hyzl offers only those. It never offers a price that is not in their plans, and never a percent off. Each plan has four parts:

Part	What it is
`name`	What Hyzl calls the plan, for example `"Pro, yearly"`. Up to 60 characters, with no link.
`price`	The price as Hyzl says it, for example `"$39.99 a year"` or `"$39.99 for the first year, then $69.99 a year"`. Up to 80 characters, with no link.
`url`	Your own https link to buy that plan. It follows the same rules as `recoveryUrl`.
`use`	`"lead"` for the plan Hyzl offers first, or `"fallback"` for a plan it offers only when needed.

Send exactly one lead, and up to three fallbacks. Hyzl leads with the lead plan in its texts, replies, calls and voicemails. It offers a fallback only when the person wants to try it first, needs it for one trip, asks for a monthly plan, or will not commit to a year. Each text names the plan whose link it sends. After a call, Hyzl texts the link of the plan that the call was about, or the lead.

{
  "offers": [
    { "name": "Pro, yearly", "price": "$39.99 a year", "url": "https://example.com/checkout/yearly-39", "use": "lead" },
    { "name": "Pro, monthly", "price": "$24.99 a month", "url": "https://example.com/checkout/monthly-24", "use": "fallback" }
  ]
}

For this person, offers replaces offerLinks, percentOff and the offer in your app settings. Hyzl also sends these links instead of recoveryUrl, whatever your link mode is. A later event with offers replaces the plans. An event without offers keeps them. When the plans change, Hyzl quotes the new price as the current one, and never says that the earlier price was wrong. Hyzl uses offers in Auto mode texts, in replies and in calls. Flow texts keep using recoveryUrl. Mark the Stripe object behind each link, as Mark the payments Hyzl recovered describes.

Send the search the person ran

Send search when the person ran a real search in your app before the paywall. The AI rep can then tell them what your app found, with your numbers exactly. Leave search out when no search finished. Send economy results only. For a premium cabin, send only how many dates had seats and the lowest points. The rep can then say that those seats exist without giving them away. A search that found nothing is still a result. Send it with an empty economy list. The rep then tells the person plainly that your app found no economy seats for those dates, and asks whether other dates or a smaller party would work.

{
  "search": {
    "ranAt": "2026-10-14T23:40:00Z",
    "searchedCabin": "business",
    "window": { "from": "2026-11-01", "to": "2026-11-30" },
    "economy": [
      { "date": "2026-11-12", "from": "TPA", "to": "LHR", "program": "Avios", "points": 30000, "taxes": 152, "currency": "USD", "seats": 4, "direct": false, "via": "MIA" }
    ],
    "premium": { "cabin": "business", "datesWithSeats": 3, "fromPoints": 57500 }
  }
}

Part	What it is
`ranAt`	When the search ran. ISO 8601 with a real date and time, for example `2026-10-14T23:40:00Z`.
`searchedCabin`	Optional. The cabin the person searched: `economy`, `premium economy`, `business` or `first`. Case does not matter, and `premium_economy` works too. Hyzl ignores any other value and keeps the rest of the search. Leave it out when your app cannot name the cabin.
`window`	The first and last day searched, as `YYYY-MM-DD`. The first day cannot be after the last.
`economy`	Up to 3 results, cheapest first. Each result has the parts below. Send an empty list, `[]`, when the search found no economy seats.
`date`	The day of the flight, as `YYYY-MM-DD`.
`from`, `to`	Three-letter airport or city codes.
`program`	The points program, up to 30 characters.
`points`	A whole number from 1 to 5,000,000.
`taxes`, `currency`	Optional. The taxes for one seat, from 0 to 100,000, and a three-letter currency code. Hyzl rounds taxes to a whole unit, so `5.60` becomes `6`. Send both or neither, and leave both out when you do not know the taxes. Hyzl treats taxes of `0`, or taxes that round to `0`, as unknown: it keeps the result, and the rep gives its points without any taxes.
`seats`	Optional. A whole number from 1 to 99.
`direct`	`true` for a nonstop flight, or `false`.
`via`	Optional. Where the flight connects, up to 10 characters.
`premium`	Optional. A `cabin` (`premium economy`, `business` or `first`), `datesWithSeats` (a whole number up to 366) and `fromPoints` (the lowest points, a whole number from 1 to 5,000,000). Leave it out when no premium seats were found. Any other cabin leaves out this part only.

program and via use letters, spaces and the characters & ' - / only: no digits, no dots and never a link. These words can appear in the first text, so a number or an address could reach the person. Apart from the cabins, if any part breaks these rules, Hyzl leaves out the whole search and still accepts the event. The response tells you what happened. A 202 response includes "search": "stored" or "search": "dropped" when your event carried a search. dropped means that the search broke a rule above, or that it is out of date: it ran before a search Hyzl already holds or, on an event without detail, before your previous event for that person arrived. Send detail with every search, so Hyzl knows which trip the search belongs to. A later event with search replaces the stored search. An event for a new trip, without a search, clears the stored search. Hyzl reads the trip from detail, up to its first comma, so "Tampa → London, business" and "Tampa → London, economy" are the same trip. That way, the rep never quotes the old trip’s numbers. You can send the search on a later event for the same person. Without occurredAt or startTimerAt, that event does not restart the timer or change when Hyzl next contacts them. Hyzl may ask you to run the search. When a person arrives without a search and you have given us an endpoint for it, Hyzl’s rep can ask your server to run that person’s search once, with their own cards and at no cost to them. Your server answers at once, runs the search, and sends the result as a paywall event with search and eventId set to <userId>:search:<request_id>, where request_id is the id Hyzl sent. Send it even when the search found nothing, with an empty economy list, or the rep cannot tell the person anything. Hyzl keeps the person’s schedule and delivers the result in the next text. Ask us to set it up. Consent is a person’s recorded permission for contact by text or call. Send the real state of your current consent choice. If you do not ask for consent, add an unchecked box beside your optional phone field. Edit this example for your business and legal requirements. Example wording:

I agree that {Your company} and its service providers may contact me by phone call and text message at the number provided, including with automated or AI-assisted technology, about my account and related offers. An AI may answer calls, and calls may be recorded and transcribed. Consent is not a condition of purchase. Message frequency varies. Message and data rates may apply. Reply STOP to opt out. Reply HELP for help. {Terms link} · {Privacy link}

Replace the placeholders with links to your Terms and Privacy Policy. Send the real consent state as consent.attested, either true or false. Never set it to true for every person. Keep the box clear by default. Keep the phone field optional. Hyzl stores a person without consent, but Hyzl does not contact that person.

Examples

curl

curl -X POST https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event \
  -H "Authorization: Bearer {{YOUR_INGEST_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "phoneNumber": "+13105551212",
    "email": "person@example.com",
    "firstName": "Sam",
    "stage": "saw_price",
    "consent": { "attested": true },
    "eventId": "paywall_abc123"
  }'

Node

// Call this at the paywall, when the person does not buy.
await fetch("https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event", {
  method: "POST",
  headers: {
    Authorization: "Bearer {{YOUR_INGEST_TOKEN}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    // Must be the same id you pass to Purchases.logIn()
    userId: user.id,
    phoneNumber: user.phoneE164,
    email: user.email,
    firstName: user.firstName,
    // The real state of your consent checkbox, not a hardcoded true
    consent: { attested: user.contactConsent === true },
    eventId: paywallView.id,
  }),
});

Swift

// Call this at the paywall, when the person does not buy.
var request = URLRequest(url: URL(string: "https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event")!)
request.httpMethod = "POST"
request.setValue("Bearer {{YOUR_INGEST_TOKEN}}", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONSerialization.data(withJSONObject: [
  // Must be the same id you pass to Purchases.logIn()
  "userId": user.id,
  "phoneNumber": user.phoneE164,
  "firstName": user.firstName,
  // The real state of your consent checkbox, not a hardcoded true
  "consent": ["attested": user.contactConsent],
  "eventId": paywallView.id,
])

let (_, response) = try await URLSession.shared.data(for: request)

Send in two steps

// Step 1, when you first know the person. No phone number yet.
await postToHyzl({ userId: user.id, email: user.email });

// Step 2, at the paywall, once you have the phone number and consent.
// Same userId. This step starts the wait.
await postToHyzl({
  userId: user.id,
  phoneNumber: user.phoneE164,
  consent: { attested: user.contactConsent === true },
});

Two events arriving together for the same userId or stripeCustomerId use one person. Each distinct event is saved. A later event can add missing details or revoke consent. A repeated eventId does not reprocess event details, even when requests arrive together with different details. An explicit optedOut: true still records STOP and withdraws contact before the duplicate response. That response names the person from the first accepted event.

Responses

Status	`error`	Meaning
202	None	Stored. `outcome` is `created` for a new person or `joined` for an existing person.
200	None	A repeated `eventId`. `outcome` is `duplicate`; event details are not reprocessed. `optedOut: true` still records STOP and withdraws contact before this response.
200	None	No person matches the withdrawal identity. `outcome` is `ignored` and `reason` is `no_person_to_withdraw`. No lead is created. `optedOut: true` still records a permanent STOP for this app and phone.
200	None	The `userId` or `phoneNumber` belongs to a support conversation your team started from the Inbox. `outcome` is `ignored` and `reason` is `support_contact`. No lead is created and no recovery starts. `optedOut: true` still records a permanent STOP for this app and phone. `consent.attested: false` still withdraws consent for that support conversation, even with a repeated `eventId`.
400	`malformed_body`	The body was not a JSON object.
400	`invalid_phone`	`phoneNumber` was sent but could not be read as E.164.
400	`invalid_consent`	`consent` was not an object, or `consent.attested` was not a boolean.
400	`invalid_opt_out`	Use a boolean for `optedOut`. `true` requires a valid E.164 `phoneNumber`, `consent.attested: false`, and `consent.voice.attested: false`.
400	`missing_durable_id`	No `userId` and no `cus_…`. Email or phone alone is not enough.
400	`invalid_recovery_url`	`recoveryUrl` was not a valid https URL.
400	`invalid_percent_off`	`percentOff` was not a whole number 1–90.
400	`invalid_offer_links`	`offerLinks` was not an object of whole percents 0–90 to https links.
400	`invalid_offers`	`offers` was not a list of 1 to 4 plans with exactly one lead, or a plan had a bad `name`, `price`, `url` or `use`.
400	`invalid_context`	`context` was not a string, or was over 1000 characters after trimming.
400	`invalid_detail`	`detail` was not a string, was over 80 characters after trimming, or contained a link.
400	`invalid_occurred_at`	`occurredAt` or `startTimerAt` could not be read, or was outside 2020–2100. Sending Unix seconds where milliseconds are expected lands here.
400	`test_requires_phone`	`test: true` without a `phoneNumber` on the same event.
401	`unauthorized`	No token: `Send your ingest token as Authorization: Bearer <token>.`
401	`unauthorized`	Wrong token: `That ingest token does not match an app.`
405	`method_not_allowed`	Use POST.
501	`sdk_not_available`	`sdk-event` only. See below.
500	`internal_error`	Ours. Retry.

Treat 200 and 202 as success. A 202 response also includes these fields:

person_id: the Hyzl record for the person.
status: the person’s current recovery state.
contactable: whether Hyzl has a phone number.
consent_attested: the consent state that Hyzl stored.
next_action_at: the next planned action time, or null.
search: stored or dropped, only when the event carried a search. See Send the search the person ran.

A 202 response means that Hyzl stored the event. It does not mean that Hyzl sent a text.

Send from your server

Do not send this event from a browser or mobile app. A public app can expose the ingest token to other people. The future sdk-event endpoint returns 501 sdk_not_available and is not deployed. Send all paywall events to paywall-event from your server.

What happens after the event

Hyzl stores the event.
Hyzl waits for the first step in your Flow.
Hyzl checks the payment provider before each step.
Hyzl stops recovery if the person paid or sent STOP.
Hyzl sends the step if the person remains eligible.

The default Flow waits five minutes, then sends one text. Its later text steps wait one day and three days. Quiet hours use the time zone for your app. The default quiet hours are 9 p.m. to 9 a.m. in that app time zone. Hyzl also holds scheduled texts outside 9 a.m. to 8 p.m. in the person’s own time zone. Hyzl reads that time zone from the phone area code, and uses your app time zone when it cannot. Hyzl holds scheduled texts until both allow them. Call steps use their own calling window. Outbound calls are off by default and only call United States and Canada numbers. A reply pauses the Flow for 24 hours while Hyzl talks with the person. Hyzl resumes the Flow only after the conversation stops and the person remains unpaid.

Get started

Install

Dashboard

Compliance

Reference