Public

Program event key, e.g. place_order, signup, birthday, social_share.

Empty string when the merchant wrote none — never null. Text fields fall back to '' so a client can print them unguarded.

Points earned (earning programs).

Points required to redeem (spending programs).

Reward kind (spending programs).

Reward amount — currency or percent depending on rewardType.

How to read pointsCost (spending programs; null for earning). On dynamic it is the STEP — the customer chooses a multiple of it — so a card must read "from 500 points", not "500 points". On fixed it is the price. The full slider bounds live on AvailableReward; this field exists so a signed-out card renders the same wording as the signed-in one.

Where the customer goes to perform the action, resolved server-side per event. Earning programs only; always null for spending. Guaranteed http(s) — non-http schemes are dropped server-side. For the 3 social events that need it (share_facebook, share_twitter, follow_twitter) this is a ready-to-open share/follow intent URL (e.g. a facebook.com/sharer.php or twitter.com/intent link), not the merchant-entered profile URL itself — the other 10 social events, plus survey/custom-program/Google-review links and the merchant's own "Add URL on click" override, resolve to that destination unchanged.

How a join_line program credits points — null for every other event, and always null on a spending program. follow_oa only pays out through POST /customer/social/line/auth-url's OAuth popup (lineUserId must be set first); join_line is claim-on-click via actionUrl / POST /customer/earn/social, same as every other social event. A missing/legacy value (predates LINE OAuth) reads as join_link.

Spend-rate programs earn points per this amount of shop currency (see ShopConfig.currency / currencyFormat), e.g. points=1 with rateMoney=1 means "1 point per $1". Null for flat-rate programs and for spending programs. This is the program's BASE rate — per-tier overrides are not reflected, as the public contract has no customer context.

The fine print a shopper needs BEFORE spending points, rendered server-side: sale channel, which products it applies to, usable-from date, minimum order, expiry, usage limit. Always present — empty means "no restrictions", and earning programs never carry any.

Whether the current customer has already completed this (non-repeatable) earning program. Only present on the personalised GET /customer/programs response — omitted entirely (the field is absent, not null) from the public, CDN-shared GET /programs response, and from every spending program. Repeatable earning events (place_order, write_review, submit_receipt, submit_form, fill_survey, milestone) always report false — there is no persistent "earned" state to track for those.

Design + approval settings, submit_form and fill_survey only — null for every other event, and always null on a spending program. autoApprove matters beyond display: POST /customer/earn for these two events already reports status: earned vs pending based on this exact flag, so without it here that switch is opaque to a headless client.

Design + reward settings, write_review only — null for every other event, and always null on a spending program.

google_maps_review only — null for every other event, and always null on a spending program. LIMITATION: the backend stores review state on the customer (customers/{id}.statusGoogleMapsReview), not per-program, so it assumes at most one active google_maps_review program per shop — every such program reports the SAME customer state. status/statusText are omitted entirely (not null-filled) on the public, CDN-shared GET /programs response, the same presence rule as isEarned; urlLocation is program-level and present on both.

streak_interact_website only — null for every other event, and always null on a spending program. UNLIKE googleReview, the ENTIRE object (including totalDays, which is program config) is personalised — present only on GET /customer/programs, and null (not a partial object) on the public, CDN-shared GET /programs response. isEarned on this same event answers a DIFFERENT question ("has the highest milestone ever been reached") — this object answers "what day is the shopper on right now, and can they claim today".

birthday only — null for every other event, and always null on a spending program. Like streak, the ENTIRE object is personalised — present only on GET /customer/programs, and null (not a partial object) on the public, CDN-shared GET /programs response. Two reasons: the birthday-entry modal this field exists for always calls GET /customer/programs anyway (it also needs Customer.birthday), and rewardOptions for a VIP-tier-scoped program can only resolve against a customer's own tier, which the public path never has. KNOWN LIMITATION: rewardOptions: [] is reported both when the program has no reward picker at all (an older layout — a reward is still granted on save, just not through a picker) AND when the picker is on but the shopper's OWN tier has zero rewards configured for it — a client cannot distinguish the two from this field alone.

The guest's ready-to-share referral link.

all — every product qualifies; products/collections are both empty and the client should render a generic "browse everything" CTA. select — only the listed products/collections qualify.

Points or spend required to reach this tier.

Present only when the merchant enables member counts.

Whether the birthday-entry modal must also collect a YEAR (not just day/month). Shop-level — shared by every date-of-birth-collecting event — derived from the birthday program's dateFormat at save time. Program.birthday.dateFormat is a different, per-program setting: it only reorders day/month for display, never adds or removes the year field.

Whether the shop is running the self-serve "opt-in" enrollment flow (Premium plan + not manual-assignment-only + the toggle is on). Combine with Customer.type to decide when to show a "Join Program" button — see POST /customer/join-program. Rides this endpoint's own 5-minute CDN cache, so a shop that just upgraded plan or flipped the toggle can take up to 5 minutes to see it reflect here.

The Facebook Page the shop currently has connected; null when it has none. Needed to build the m.me/{facebookPageId}?ref=... Messenger link that links a shopper's Facebook account — a client constructs that link itself, no signing endpoint required: the ref payload is signed with the shop's own id as the HMAC key, which an authenticated caller already holds as a plaintext claim in its JWT. This is shop CONFIGURATION, not link state: whether the current shopper is connected is Customer.social.facebookConnected. Rides this endpoint's 5-minute CDN cache, same staleness as optInEnrollmentEnabled.

The published structure document. Shape is owned by the admin editor and the storefront renderer jointly — sections[] (id + enabled + order) plus content, theme and layout keyed by section id.

Already sorted; a consumer should render it as given. orderBy still travels so the two hosts emit the same shape, and so a consumer that does sort has the field to sort on rather than an undefined.