--- title: "Examine rewards" method: POST path: "/v2/loyalties/examine/rewards" tags: ["Examine"] --- # Examine rewards `POST /v2/loyalties/examine/rewards` Evaluates rewards assigned to a customer's active Loyalty v2 program memberships. Applies temporary customer and member metadata overrides without updating stored data. Returns reward availability by card, including points costs and applicable unavailability reasons. This endpoint can examine rewards for all loyalty programs the customer belongs to by using `customer_identification` with `customer_id` or `source_id`. To examine rewards only for one program, use `member_id` in `customer_identification`, as `member_id` is loyalty program-specific. ## Request body - ExamineRewardsRequest — Request body for examining rewards. - `customer_identification` ExamineCustomerIdentification, required — Identifies the customer to examine. Depending on `type`, requires one of `customer_id`, `customer_source_id`, or `member_id`. Non-selected identifiers may be omitted or set to `null`. - `type` 'customer_id' | 'customer_source_id' | 'member_id', required — Identification method. - `customer_id` string, nullable — Unique customer ID (`cust_...`). Required when `type` is `customer_id`. - `customer_source_id` union — Customer source ID, e.g. from an external system. May be provided as a string or a number. Required when `type` is `customer_source_id`. - string - number - `member_id` string, nullable — Loyalty member ID (`lmbr_...`). Required when `type` is `member_id`. - `customer` object — Provides temporary customer metadata overrides for the examination. Merges them with stored metadata without updating the customer. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `member` object — Provides temporary member metadata overrides for the examination. Requires `customer_identification.type` to be `member_id`. Merges them with stored metadata without updating the member. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. ## Response `200` Rewards examination result - ExamineRewardsResponse - `customer` ExamineCustomerReference, required — Customer reference in examine results. - `id` string, required — Unique customer ID (`cust_...`). - `source_id` string, nullable, required — Customer source ID. - `metadata` object, required — Customer metadata (empty object when unset). - `object` 'customer', required — Object type marker. Always `customer`. - `rewards` ExamineRewardsRewardDetail[], required — Lists rewards included in the returned card estimations. - `id` string, required — Unique reward ID (`lrew_...`). - `name` string, required — Reward name. - `type` 'MATERIAL' | 'DIGITAL', required — Reward type. - `metadata` object, required — Reward metadata (empty object when unset). - `object` 'reward', required — Object type marker. Always `reward`. - `purchase_limits` RewardPurchaseLimits — Limits on how often a member can purchase the reward. Always present on reward responses; defaults to no cooldown and no frequency limit. - `cooldown` RewardPurchaseLimitsCooldown — Purchase cooldown limits for a reward. - `type` 'NO_COOLDOWN' | 'FIXED_COOLDOWN', required — Cooldown type. `NO_COOLDOWN` - no cooldown. `FIXED_COOLDOWN` - wait a fixed period after each purchase. - `fixed_cooldown` RewardPurchaseLimitsCooldownFixedCooldown — Fixed cooldown configuration. - `period` RewardPurchaseLimitsCooldownFixedCooldownPeriod, required — Fixed cooldown period after a reward purchase. - `value` integer, required — Length of the cooldown period. - `unit` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required — Unit of the cooldown period. - `frequency` RewardPurchaseLimitsFrequency — Purchase frequency limits for a reward. - `type` 'NO_LIMIT' | 'LIMITED', required — Frequency limit type. `NO_LIMIT` - unlimited purchases. `LIMITED` - limited by the `limits` array. - `limits` RewardPurchaseLimitsFrequencyLimit[], required — Frequency limit definitions. Empty array when `type` is `NO_LIMIT`; one entry when `type` is `LIMITED`. - `type` 'TIME_BASED', required — Limit type. Always `TIME_BASED`. - `period` CardDefinitionLimitTimeBasedPeriod, required — Time-based limit period. - `type` 'CURRENT_PERIOD', required — Period type. - `current_period` object — Current-period configuration. Present when `type` is `CURRENT_PERIOD`. - … - `triggers` RewardPurchaseLimitsFrequencyLimitTriggers, required — Maximum number of purchases allowed in the period. - `max` integer, required — Maximum number of purchases in the configured period. - `memberships` ExamineRewardsMembership[], required — Reward opportunities per program membership. - `member` ExamineMemberReference, required — Member reference in examine results. - `id` string, required — Unique member ID (`lmbr_...`). - `customer_id` string, required — Unique customer ID the member belongs to. - `program_id` string, required — Unique program ID the member belongs to. - `metadata` object, required — Member metadata (empty object when unset). - `object` 'member', required — Object type marker. Always `member`. - `program` ExamineProgramReference, required — Program reference in examine results. - `id` string, required — Unique program ID (`lprg_...`). - `name` string, required — Program name. - `metadata` object, required — Program metadata (empty object when unset). - `object` 'program', required — Object type marker. Always `program`. - `cards` ExamineRewardsCardEstimation[], required — Reward estimations per card. - `card` ExamineCardReference, required — Card reference in examine results. - `id` string, required — Unique card ID (`lcrd_...`). - `card_definition_id` string, required — Unique card definition ID (`lcdef_...`). - `card_type` 'INDIVIDUAL', required — Card type. Currently only `INDIVIDUAL` exists. - `code` string, nullable, required — Card code. May be `null` right after member creation because card codes are generated asynchronously. - `object` 'card', required — Object type marker. Always `card`. - `rewards` ExamineRewardsCardRewardEstimation[], required — Reward availability estimations for this card. - `reward` ExamineRewardsRewardReference, required — Reward reference. - `id` string, required — Unique reward ID (`lrew_...`). - `object` 'reward', required — Object type marker. Always `reward`. - `status` 'AVAILABLE' | 'UNAVAILABLE', required — Whether the reward can currently be obtained with this card. - `cost` ExamineRewardsRewardCost, required — Reward cost. - `points` number, required — Points cost of the reward for this card. - `object` 'reward_cost', required — Object type marker. Always `reward_cost`. - `unavailability_reasons` ExamineRewardsRewardUnavailabilityReason[] — Reasons the reward is unavailable. Absent when the reward is available. - `reason` 'insufficient_balance' | 'no_target_card', required — Identifies why the reward is unavailable. - `insufficient_balance`: The source card balance is lower than the required points cost. - `no_target_card`: The member does not have the loyalty card that would receive the points from a "points on a loyalty card" reward. - `details` union, required — Provides values related to the unavailability reason. - object — Provides balance details for `insufficient_balance`. - … - object — Identifies the missing target card for `no_target_card`. - … - `object` 'reward_unavailability_reason', required — Object type marker. Always `reward_unavailability_reason`. - `object` 'reward_estimation', required — Object type marker. Always `reward_estimation`. - `object` 'card_estimation', required — Object type marker. Always `card_estimation`. - `object` 'member_rewards_opportunity', required — Object type marker. Always `member_rewards_opportunity`. - `object` 'rewards_examine_result', required — Object type marker. Always `rewards_examine_result`. ## Other responses - `400` — Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state. - `404` — Resource not found. - `500` — Unexpected server error. --- [API](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-loyalty-v2-api/revisions/69be73b5cff0/schema)