--- title: "Examine rewards" method: POST path: "/v2/loyalties/examine/rewards" tags: ["Examine"] --- # Examine rewards `POST /v2/loyalties/examine/rewards` ## Request - Base URL: `https://api.voucherify.io` - URL: `https://api.voucherify.io/v2/loyalties/examine/rewards` - Auth: one of: - API key in header `X-App-Id` and API key in header `X-App-Token` - HTTP bearer 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. Omits a reward when it is inactive, out of stock, has no matching cost, or the member has no card for that cost. This endpoint can examine rewards for all loyalty programs the customer belongs to by using `customer_identification` with `customer_id` or `customer_source_id`. To examine rewards only for one program, use `member_id` in `customer_identification`, as `member_id` is loyalty program-specific. A customer who exists but has no active membership returns `200` with an empty `memberships` array. ## Request body - LoyaltiesExamineRewardsExamineRequestBody: Request body schema for **POST** `/v2/loyalties/examine/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` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `member` object: Overrides member metadata for this examination. Send it only when `customer_identification.type` is `member_id`. Merges the override with stored metadata without updating the member. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. ## Response `200` Rewards examination result. An empty `memberships` array means the customer has no active membership. An empty `cards` array means no assigned reward resolved onto a card. - LoyaltiesExamineRewardsExamineResponseBody: Response body schema for **POST** `/v2/loyalties/examine/rewards`. - `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` LoyaltiesExamineRewardsExamineResponseBodyRewardDetail[], required: Lists rewards that resolved a points cost and appear on a returned card. Omits a reward when it is inactive, out of stock, has no matching cost, or the member has no card for that cost. - `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, required: 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` LoyaltyV2ActivityRewardPurchaseLimitsCooldownFixedCooldownPeriod, 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, required: 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` LoyaltyV2ActivityCardDefinitionLimitTimeBasedPeriod, required: Time-based limit period. - `type` 'CURRENT_PERIOD', required: Period type. - `current_period` object: Current-period configuration. Present when `type` is `CURRENT_PERIOD`. - … - `triggers` LoyaltyV2ActivityRewardPurchaseLimitsFrequencyLimitTriggers, required: Maximum number of purchases allowed in the period. - `max` integer, required: Maximum number of purchases in the configured period. - `memberships` LoyaltiesExamineRewardsExamineResponseBodyMembership[], required: Lists one entry for each active membership whose program has reward assignments. `cards` can be empty when none of those rewards resolve onto a card. - `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` LoyaltiesExamineRewardsExamineResponseBodyCardEstimation[], required: Lists cards that have at least one reward with a resolved points cost. Can be empty. - `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` LoyaltiesExamineRewardsExamineResponseBodyCardRewardEstimation[], required: Reward availability estimations for this card. - `reward` LoyaltiesExamineRewardsExamineResponseBodyRewardReference, 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` LoyaltiesExamineRewardsExamineResponseBodyRewardCost, 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` LoyaltiesExamineRewardsExamineResponseBodyRewardUnavailabilityReason[]: 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`: The request body failed validation. Sending `member` when `customer_identification.type` is not `member_id` returns key `invalid_payload`, message `Invalid payload`, and details `Property 'member' is only allowed when customer_identification.type is 'member_id'`. Customer or member metadata that does not match its metadata schema returns key `metadata_validation_failed` and message `Metadata validation failed`. - `404`: The `member_id` does not exist, or the `customer_id` or `customer_source_id` does not exist. An unknown `member_id` is checked first and returns `resource_type` `member` with details `Cannot find member with id {memberId}`. An unknown customer returns `resource_type` `customer` with details `Cannot find customer with id {id}`, where `{id}` is the `customer_id` or `customer_source_id` you sent. When a member exists but its customer record does not, that same customer error uses the `member_id` as `{id}`. - `500`: Internal server error. ## Changes - **2026-10-12** (v2) `d050da3a1603`: 1 breaking, 4 info - the `rewards/items/purchase_limits/cooldown/fixed_cooldown` response's property type changed from no type to `object` for status `200` - the response property `rewards/items/purchase_limits/cooldown` became required for the status `200` - the response property `rewards/items/purchase_limits/frequency` became required for the status `200` - removed `#/components/schemas/RewardPurchaseLimitsCooldownFixedCooldown, subschema #2` from the `rewards/items/purchase_limits/cooldown/fixed_cooldown` response property `oneOf` list for the response status `200` - …1 more - **2026-10-12** (v2) `c56e6909b766`: 5 breaking - the response property `rewards/items/purchase_limits/cooldown` became optional for the status `200` - the response property `rewards/items/purchase_limits/frequency` became optional for the status `200` - added `#/components/schemas/RewardPurchaseLimitsCooldownFixedCooldown, subschema #2` to the `rewards/items/purchase_limits/cooldown/fixed_cooldown` response property `oneOf` list for the response status `200` - the `rewards/items/purchase_limits/cooldown/fixed_cooldown` response's property type changed from `object` to no type for status `200` - …1 more - …earlier changes not shown [Operation history](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/changes/v2/loyalties/examine/rewards/post.md) --- [API](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api.md) - [All operations](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/revisions/e0d9f2d2532f?raw)