Membership benefits and personal perks
View .mdRead GET /v1/developer/guest/me through the SDK’s same-origin guest client. The installation credential scopes the collection and the guest session scopes the person. Never accept a guest ID from the browser.
import { createKismetGuestBrowserClient } from '@kismet-tech/sdk/react';
const guest = createKismetGuestBrowserClient();const account = await guest.getSelf();const program = account.membershipProgram;const personalPerks = account.benefits;REST calls from the server require both the Developer credential and the BFF-held guest token:
curl "$KISMET_API_ORIGIN/v1/developer/guest/me" \ -H "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \ -H "X-Kismet-Guest-Token: $KISMET_GUEST_ACCESS_TOKEN"Program catalog
Section titled “Program catalog”membershipProgram carries programEnabled, collectionId, benefits, and partnerBenefits. Included benefits contain a name, optional description and named items. Partner offers include the headline, promise, provider and award trigger. Copy and conditions come from the canonical collection perks service. Home-scoped benefits are excluded from this collection-wide read.
This is the advertised catalog, not a personal award. Check the returned membership for ACTIVE status before presenting it as the guest’s program. Offer eligibility, consent, availability and fulfillment conditions still apply. Reading the account never enrolls the guest, awards a perk, changes a price or requests fulfillment.
programEnabled: false means disabled. null means the program read was unavailable. An omitted field means that API version does not provide it. Keep these distinct from a successful empty list.
Personal entitlements
Section titled “Personal entitlements”benefits contains the guest’s partner-code COUPON entitlements: perkId, name, headline, promise, provider, state, award date, redeem-by date and email delivery status. An awarded, unexpired benefit can also include guest-owned redemption details. Older responses may omit that field; unavailable details are null.
Recognize an already-saved offer
Section titled “Recognize an already-saved offer”An offer’s id matches the personal benefit’s perkId. Use the authenticated guest account read for the same collection and environment, and compare those identifiers exactly—never names or providers. Only show an actionable saved offer when state is awarded, redemption is present, and its expiry is absent or still in the future.
If capture returns IDEMPOTENCY_CONFLICT, refresh the authenticated account. An exact eligible benefit allows an “Already saved” result linking to the guest’s account. This read does not create a capture, resend email, or prove a new delivery; do not record it as a new conversion. Keep the conflict if no eligible match is returned. The bounded benefits read is not proof that an absent offer was never awarded, and changing an idempotency key must not be used to force another email.
| State | Display meaning |
|---|---|
pending |
Conditions have not yet produced an award |
awarded |
Awarded; check the redeem-by date before showing as available |
redeemed |
Used |
expired |
Expired |
revoked |
No longer available |
failed |
Unavailable |
Keep future states displayable but non-actionable. An omitted benefits field is unsupported, not proof of zero perks. An empty array is a successful read with no returned entitlements. The read scans the latest 50 partner perk events and returns at most one per perk, so it is not a lifetime entitlement ledger. Personal booking discounts are returned separately in entitlements, as described below.
TEST installations see sandbox personal events only. LIVE excludes them. The program catalog is shared public copy; TEST does not manufacture a separate member program. Re-read after login or account changes, and do not cache this private response publicly. This is display data, never redemption authority.
Personal booking discounts in a perks drawer
Section titled “Personal booking discounts in a perks drawer”GET /v1/developer/guest/me also returns entitlements for the authenticated
guest, installation collection and environment. The SDK preserves these on
getSelf(); no guest ID or manager ID comes from browser input.
import { createKismetGuestBrowserClient } from '@kismet-tech/sdk/react';
const guest = createKismetGuestBrowserClient();const account = await guest.getSelf();const discounts = account.entitlements;const usable = discounts?.filter((perk) => perk.state === 'awarded' && perk.redemption !== null && new Date(perk.expiresAt).getTime() > Date.now());Each booking_discount entitlement includes its ID, perk ID, guest-facing name
and description, fixed amount in minor units or integer percentage, currency,
eligible property IDs, expiry, optional stay dates and minimum nights. Display
those terms in the drawer. propertyIds is the frozen set of eligible homes;
homes added to a collection or group later do not automatically join an existing
perk. A home removed from the manager’s collection cannot redeem the award.
States are awarded, reserved, redeemed, expired and revoked. Keep unknown
future states readable and non-actionable. redemption is null unless the award
is available and the authenticated guest’s email is verified. A reserved award
belongs to a payment attempt; do not offer it for a second checkout. A failed or
uncertain payment attempt may need reconciliation before it can be reused.
Partner benefits, booking discounts and standing membership awards are separate personal sources. An advertised program is never evidence of an award.
The read returns at most the latest 200 personal discount awards. An omitted field means this server does not support the projection; an empty array means no awards were returned. It is not a complete historical ledger. Refresh after an award or booking instead of inferring redemption from a client click.
Awards are personal and single-use, without stacking. A code alone is not permission to redeem: supported Kismet native checkout verifies the guest, collection, home, currency, stay and current award state before charging. This slice supports single-installment native checkout. External booking engines, request-to-book, and other payment paths do not gain personal-discount support from this read. Display the final payable price from checkout; never subtract this amount from a cached or PMS quote yourself. Keep redemption codes out of analytics, logs, URLs and public HTML.
Managers create or reuse these perks in Insiders for an individual guest or a
saved audience. Platform MCP provides list_discount_perks,
preview_discount_perk and award_discount_perk under collection manager
permissions. The Developer API and guest SDK only read the resulting awards.
TEST and LIVE awards are isolated. Reading an account never enrolls the guest,
issues an award, sends an email or initiates a payment.
Standing membership award history
Section titled “Standing membership award history”Where supplied, account.standardEntitlements contains { data, nextCursor }. Each personal record carries its frozen definition (title, conditions, cadence, allowance and fulfillment terms), lifecycle state, period and nullable expiry. Preserve history across pages and guest-session changes; do not replace these frozen terms with the current advertised catalog.
const next = await guest.getSelf({ standardEntitlementCursor: account.standardEntitlements?.nextCursor ?? undefined,});The browser client, same-origin Next handler and server client forward this cursor through the authenticated self read. Cursor values must be UUIDs. An omitted history field is unavailable or unsupported; an empty data array is a successful empty page. Only show an account-wide empty state when every supported personal source is known and empty.
Standing awards have redemption: null, fulfillment: 'not_confirmed' and capability: 'unavailable'. A free-night allowance is not a reservation or a checkout discount. Reading or displaying any award does not apply it to a quote. Keep partner and booking redemption codes out of logs, analytics, URLs and public HTML.