Customer

0–100.

Entry threshold of the customer's current tier (0 for the base tier).

Entry threshold of the next tier.

Whether the customer has hit the limit for the current period.

Merchant-formatted date the period resets. Empty string for a customer whose tier has an unlimited override.

Server-rendered warning sentence, ready to show as-is. null when reached is false — there is no sentence to show until then.

The handle the customer entered via POST /customer/social/instagram/link; null when they have never linked one (or unlinked). Unlike the LINE/Facebook fields this IS the raw value, because the modal renders it: it pre-fills the input and prints the current username. Never verified for ownership — Instagram linking is a self-declared string, not OAuth.

Whether the customer completed LINE Login (POST /customer/social/line/auth-url → OAuth popup). A boolean, not the LINE user id — a client needs only the answer, not the platform identifier. REQUIRED READ before claiming a join_line program whose Program.lineJoinType is follow_oa: POST /customer/earn rejects those with LINE_NOT_LINKED (400) until this is true, so a client must open the OAuth popup instead of attempting the claim.

Whether the customer also follows the shop's LINE Official Account. A SEPARATE step from lineLinked — set by the LINE follow/unfollow webhook, and it can go back to false if they unfollow. Drives whether a "Follow" CTA still shows.

Whether the customer has a Messenger link that is still usable — i.e. they linked one AND it is scoped to the page the shop currently has connected. Resolved server-side; false (not stale-true) after a merchant reconnects a different page, since every previously stored link becomes unreachable. The underlying Page-Scoped User ID is never exposed: a client needs only this boolean to choose between the connect and disconnect branches (POST /customer/social/facebook/disconnect).

Display name Meta returned when the link was made, for a "Connected as {name}" label. Null when facebookConnected is false, and null when Meta sent no name — render a bare "Connected" in that case.

Whether the shopper must attach an image with their submission.

When true, POST /customer/earn reports status: earned immediately; when false, status: pending until a merchant approves the submission in admin.

Whether a smaller reward is granted immediately, ahead of approval.

The instant reward amount, when instantRewardEnabled is true.

Where to send the shopper back to AFTER they finish writing the review — NOT a CTA (actionUrl is always null for write_review; this is a distinct field). Guaranteed either an absolute http(s) url or a root-relative path (/collections/all style) — non-http(s) schemes and protocol-relative (//host) values are dropped server-side. Null when the merchant left it blank — pick your own fallback (for example /collections/all).

Bonus points awarded on top of the base reward for this program.

The Google Maps location the shopper reviews. Guaranteed http(s) — non-http schemes are dropped server-side.

The shopper's own review, if any. null means never submitted — the only one of the 4 states with no persistent record on the customer. rejected is the only state the shopper can act on again (resubmit); pending and approved are dead ends. Personalised path only — see the description above.

null when status is null: "never submitted" is a 3-step guided form, not a single sentence, and stays entirely client-owned UI. Personalised path only, same rule as status.

The streak day the shopper is currently on (0 before their first claim). Resets to 0 after a missed day or when returning to this program from a different one.

The highest streak milestone day configured on this program.

Whether calling POST /customer/earn for this program right now would award points. false covers two different terminal states for today: an ordinary same-day cooldown (already claimed, come back tomorrow) and a program that can no longer be completed at all (not enough days left before it ends) — message is the only field that tells them apart.

Non-null ONLY when the program can no longer be completed (not enough days remain before its endDate to reach totalDays) — every other state, including an ordinary same-day cooldown, has nothing extra to say and reports null.

The rewards this shopper may choose from.

Whether the shopper may pick exactly one reward (render radio buttons) or several (checkboxes). Independent of whether rewardOptions is empty — still reflects the merchant's configured mode even with nothing to pick.

Day/month display ORDER for the birthday-entry modal's date input — NOT whether a year is collected at all (see ShopConfig.isNewFormatDOB for that).

Program event key — the same values as Program.key. Clients map their built-in icons off it; matching Program.key is what keeps the icon stable when the personalised list replaces the SSR'd one.

The merchant's uploaded icon, when they set one. Built-in per-event icons are not URLs — map those client-side off key.

The reward's fine print, rendered server-side — same rows the matching Program carries. Empty means no restrictions.

When redeemType is fixed, the price. When dynamic, the STEP — how many points buy one rewardValue of discount. Read redeemType before treating this as a price.

Discount gained per pointsCost points.

dynamic means the customer chooses a multiple of pointsCost between minPoints and maxPoints, and POST /customer/redeem REQUIRES points. This is the default for "Amount discount" programs, so it is the common case, not an edge one.

Dynamic only, and only when the merchant set a floor. Null = unbounded.

Dynamic only, and only when the merchant set a ceiling. Null = unbounded.

Whether the merchant capped how much of a cart this reward may discount. Always false when redeemType is fixed — there is no slider to cap.

The cap, as an INTEGER PERCENT of the cart total (1-100) — not an amount. Null when hasLimitCartValue is false. Resolving it needs the cart total, which only the storefront holds, so the ceiling is computed CLIENT-side:

maxPointsNoCap = maxPoints ?? (customerPoints - customerPoints % pointsCost) maxPointsByCart = floor((limitCartValue / 100 * cartTotal) / rewardValue + 0.0001) * pointsCost ceiling = min(maxPointsNoCap, maxPointsByCart)

This is a DISPLAY cap: POST /customer/redeem does not receive a cart total and does not enforce it (no Joy surface does today).

Whether the customer can afford the cheapest redemption this program allows — minPoints when there is one, else pointsCost.

free_product rewards only. one — the customer must pick one gift from giftProducts and send it back as variantId on POST /customer/redeem. all — the reward covers every configured product, nothing to pick. Null for every other reward type.

The gifts to choose between when giftSelectionMode is one. Empty otherwise, and empty for collection-scoped gifts — those select a collection rather than a variant, which a storefront cannot add to a cart.

Environmental-impact reward only ("Plant a tree"): the provider that fulfils it. null on every other reward type. Absent on older backends.

Impact reward only — what is created (e.g. tree). null otherwise.

Impact reward only — how many units per redemption. null otherwise.

Impact reward only — the merchant's public impact dashboard link. null otherwise.

Buy-X-Get-Y reward only — the specific products the customer gets. [] otherwise.

BXGY only — the collections the customer gets. [] otherwise.

BXGY only — how many "buy" items are required. null otherwise.

BXGY only — whether a per-order use cap is set. false otherwise.

BXGY only — the per-order use cap when enableMaximumUsesPerOrder. null otherwise.

Whether the merchant lets a redeemer gift this coupon on to a friend — drives the "Send to a friend" button (backend endpoint already exists). false when off. Absent on older backends.

When the send-to-friend flow routes through an automation, which provider. null when sendRewardToFriend is off or no provider is configured.

The coupon's own id — NOT the program's.

The source program's event, same meaning as AvailableReward.key — what a client maps its built-in icon off. Empty string when the coupon's program snapshot never recorded one.

Merchant-uploaded icon for the source program; null when they set none. Built-in per-event icons are not served — clients map those off key.

How the coupon may be used. The shopper needs this AFTER redeeming too — "Minimum order $50" is why a code looks broken at checkout.

Points actually spent at redemption time.

notYetUsable means the coupon exists but startsAt is in the future — show "Active from …" rather than an Add-to-cart button, which checkout would reject.

Null when the coupon never expires.

Null when it is usable immediately.

The variant that WAS chosen, on a redeemed free_product reward — lets a client still add the gift to the cart later.

Full picked-product info for an already-redeemed free-gift coupon — what the core coupon list needs to render the product row + Add-to-cart (giftVariantId alone is not enough). [] on non-free-gift coupons. Absent on older backends.

one | all | null — which free-gift picker the core renders.

The already-chosen variant (same value as giftVariantId).

Collections a collection-scoped free gift hands out (the case freeGiftProducts is empty for). [] on every other coupon.

Gift card spent down but still has balance — show the "Partially used" badge. Absent on older backends.

The gift card's real remaining balance. null when the card was never refreshed or this isn't a gift card — use rewardValue (face value) for the amount label instead. Absent on older backends.

The gift's own id — NOT the sender's reward id, and NOT the program's. Also the cursor for before/after.

The source program's event, same meaning as AvailableReward.key — what a client maps its built-in icon off.

The source program's title, in locale when the merchant translated it. Read off the snapshot the gift carries, so a gift issued from a program the merchant has since deleted still has a title.

The source program's sentence, localized and snapshot-read the same way as title.

Merchant-uploaded icon for the source program; null when they set none. Built-in per-event icons are mapped client-side off key.

MASKED for a gift card — the spendable full code is repo-private and never leaves the server.

Always active in practice — used, revoked and expired gifts are filtered out of the page. Present so a client can render a gift and a redeemed coupon through one card component.

Mirrors the sender's coupon so both lapse together. Null when the gift never expires.

Always null today — the gift record carries no start date.

On a free_product gift, the variant the sender chose.

Full picked-product info for an already-received free-gift gift — same shape and purpose as RedeemedReward.freeGiftProducts. [] on non-free-gift gifts. Absent on older backends.

one | all | null — which free-gift picker the core renders.

The variant the sender chose (same value as giftVariantId).

Collections a collection-scoped free gift hands out. [] on every other gift.

Who sent it. Empty string when unknown — show the name, falling back to senderEmail.

The sender's email, empty string when unknown. Display-safe by design: it is one of only two sender fields stored on the gift.

The gift's fine print, rendered server-side in the resolved locale — the same rows, from the same builder, as the matching RedeemedReward, so a gift and an own coupon from one program read identically on a shared card. Empty array (never null) when the program carries no restrictions.

True when this is a gift card that has been spent down but still has a balance — show a "Partially used" badge. Stays false for every non-gift-card reward.

The gift card's real remaining balance. Null when the card was never refreshed against Shopify or this reward is not a gift card — a client falls back to rewardValue (the face value) in that case.

Shopify product id (numeric, unprefixed) — the same string as GiftProduct.id, so the two lists join directly.

True when at least one of this product's variants is available.

Opaque step identity, echoed back on claim. A raw milestone value on a plain program; {programId}_{stepType}_{value} on milestone_mixed. Also the React key — stable across refetches.

This step's own metric — the program's typeMilestone on a plain program, the step's own on milestone_mixed. Drives which built-in icon the client draws in the circle.

The step sentence: "After spending $500", "After completing 3 orders", or the merchant's own per-step description when they wrote one (their translation for the served locale wins). '' only when the step type has no sentence.

locked — not reached. current — the step being worked towards; the only one carrying progress. claimable — reached, rewards still to pick: render the radio list and the Claim button. achieved — reached and rewarded. passed_unclaimed — the counter passed this step but no reward was recorded; render note as a tooltip beside the label.

Whether the circle and the connector above it are filled. Separate from state on purpose — on milestone_mixed a step counts as reached by its position in the sequence, not by its own counter.

Tooltip text for passed_unclaimed. Null in every other state.

How many rewards the shopper may pick when state is claimable. 1 unless the merchant raised it. The Claim button stays disabled until exactly this many are selected.

Present only when state is current.

Opaque step identity, echoed back on claim. A raw milestone value on a plain program; {programId}_{stepType}_{value} on milestone_mixed. Also the React key — stable across refetches.

This step's own metric — the program's typeMilestone on a plain program, the step's own on milestone_mixed. Drives which built-in icon the client draws in the circle.

The step sentence: "After spending $500", "After completing 3 orders", or the merchant's own per-step description when they wrote one (their translation for the served locale wins). '' only when the step type has no sentence.

locked — not reached. current — the step being worked towards; the only one carrying progress. claimable — reached, rewards still to pick: render the radio list and the Claim button. achieved — reached and rewarded. passed_unclaimed — the counter passed this step but no reward was recorded; render note as a tooltip beside the label.

Whether the circle and the connector above it are filled. Separate from state on purpose — on milestone_mixed a step counts as reached by its position in the sequence, not by its own counter.

Tooltip text for passed_unclaimed. Null in every other state.

How many rewards the shopper may pick when state is claimable. 1 unless the merchant raised it. The Claim button stays disabled until exactly this many are selected.

Present only when state is current.