> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi/loyalties-v2.json post /v2/loyalties/examine/rewards openapi: 3.1.0 info: title: Voucherify Loyalty v2 API version: 2.0.0 description: >- Complete OpenAPI specification for the Voucherify Loyalty v2 API. All endpoints require the LOYALTY_V2 feature flag. Combined from per-domain specs: programs.yaml, members.yaml, program-operations.yaml, card-definitions.yaml, earning-rules.yaml, tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml servers: - url: '{protocol}://{host}' variables: protocol: default: https enum: - https - http host: default: api.voucherify.io security: - X-App-Id: [] X-App-Token: [] - bearerAuth: [] tags: - name: Programs description: >- Loyalty program CRUD, lifecycle management, program-scoped resource assignments (card definitions, earning rules, rewards, tier structures), member management (create, list, get, update, activate, deactivate, delete), membership retrieval (member + program + cards with tier progress, by customer ID, customer source ID, or member ID), card operations (points adjustment, pending points, expiring points, transactions), reward purchases, and activity history. - name: Card definitions description: >- CRUD operations, lifecycle management, and activity history for card definitions. Card definitions describe the configuration for loyalty cards, including code generation, points expiration, earning/spending limits, pending points, refunds, and balance settings. - name: Earning rules description: >- Manage earning rules that define how customers earn points or receive incentives based on triggers (events, segments, custom events). Includes CRUD, lifecycle, and activity history. - name: Tier structures description: >- CRUD operations, lifecycle management, and activity history for tier structures. Includes nested tier definitions (create, list, update, delete) within tier structures. Tier structures define the tiering model for loyalty programs — how members qualify for and move between tiers. - name: Benefits description: >- Manage benefit definitions (fixed points, proportional points, material, digital). Includes CRUD, lifecycle transitions, and activity history. - name: Rewards description: >- CRUD, lifecycle operations, and activity history for reward definitions. Rewards can be material (product/SKU) or digital (discount coupons, gift vouchers). - name: Examine description: >- Evaluation endpoints that estimate earning opportunities and reward availability for a customer across their loyalty program memberships, without side effects. paths: /v2/loyalties/examine/rewards: post: tags: - Examine summary: Examine rewards description: >- 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. operationId: examineRewards requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExamineRewardsRequest' responses: '200': description: Rewards examination result content: application/json: schema: $ref: '#/components/schemas/ExamineRewardsResponse' examples: Examine reward: value: customer: id: cust_6onRrs4kCnvSVrTs5YtDPFBG source_id: lx-rdmptr metadata: VIP: true object: customer rewards: - id: lrew_128f4cab04147c8608 name: Free item coupon type: DIGITAL metadata: {} object: reward purchase_limits: cooldown: type: FIXED_COOLDOWN fixed_cooldown: period: value: 1 unit: DAY frequency: type: LIMITED limits: - type: TIME_BASED period: type: CURRENT_PERIOD current_period: unit: DAY triggers: max: 1 - id: lrew_128f4c6710947c85d1 name: Minas Gerais 500 type: MATERIAL metadata: {} object: reward purchase_limits: cooldown: type: NO_COOLDOWN frequency: type: NO_LIMIT limits: [] - id: lrew_1294cebb458e4904a0 name: Carioca shirt type: MATERIAL metadata: {} object: reward purchase_limits: cooldown: type: NO_COOLDOWN frequency: type: NO_LIMIT limits: [] - id: lrew_12b22d6ef31184e002 name: Carioca shorts type: MATERIAL metadata: {} object: reward purchase_limits: cooldown: type: NO_COOLDOWN frequency: type: NO_LIMIT limits: [] - id: lrew_12bb65405edf8d3dec name: Carioca longsleeve type: MATERIAL metadata: {} object: reward purchase_limits: cooldown: type: NO_COOLDOWN frequency: type: NO_LIMIT limits: [] memberships: - member: id: lmbr_128f962dbc8c4ba5dc customer_id: cust_6onRrs4kCnvSVrTs5YtDPFBG program_id: lprg_128f58429f4c4bf7b2 metadata: {} object: member program: id: lprg_128f58429f4c4bf7b2 name: AnnualProgram metadata: {} object: program cards: - card: id: lcrd_128f962dbd8c4ba5e1 card_definition_id: lcdef_128f4a88414c4bed69 card_type: INDIVIDUAL code: AnnualTime-7M7ShPGfme object: card rewards: - reward: id: lrew_128f4cab04147c8608 object: reward status: AVAILABLE cost: points: 300 object: reward_cost object: reward_estimation - reward: id: lrew_128f4c6710947c85d1 object: reward status: AVAILABLE cost: points: 150 object: reward_cost object: reward_estimation - reward: id: lrew_1294cebb458e4904a0 object: reward status: AVAILABLE cost: points: 500 object: reward_cost object: reward_estimation object: card_estimation - card: id: lcrd_128f962dbd8c4ba5df card_definition_id: lcdef_128f495f720c4bec8c card_type: INDIVIDUAL code: SummerTime-7z8dWawICd object: card rewards: - reward: id: lrew_12b22d6ef31184e002 object: reward status: UNAVAILABLE cost: points: 321 object: reward_cost unavailability_reasons: - reason: insufficient_balance details: required: 321 available: 10 missing: 311 object: reward_unavailability_reason object: reward_estimation object: card_estimation object: member_rewards_opportunity object: rewards_examine_result '400': description: >- Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Customer not found: value: code: 404 key: not_found message: Resource not found details: Cannot find customer with id cust_6onRrs4kCnvSVrTs5YtDPFB request_id: v-12c2e64d5d4a67cddc resource_id: cust_6onRrs4kCnvSVrTs5YtDPFB resource_type: customer '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ExamineRewardsRequest: type: object description: Request body for examining rewards. properties: customer_identification: $ref: '#/components/schemas/ExamineCustomerIdentification' description: Identifies the customer or loyalty member to examine. customer: type: object description: >- Provides temporary customer metadata overrides for the examination. Merges them with stored metadata without updating the customer. additionalProperties: false properties: metadata: description: >- Overrides customer metadata for this examination. Set to `null` to apply no override. oneOf: - $ref: '#/components/schemas/Metadata' - type: 'null' member: type: object description: >- 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. additionalProperties: false properties: metadata: description: >- Overrides member metadata for this examination. Set to `null` to apply no override. oneOf: - $ref: '#/components/schemas/Metadata' - type: 'null' required: - customer_identification additionalProperties: false ExamineRewardsResponse: type: object properties: customer: $ref: '#/components/schemas/ExamineCustomerReference' description: Identifies the customer used for the examination. rewards: type: array description: Lists rewards included in the returned card estimations. items: $ref: '#/components/schemas/ExamineRewardsRewardDetail' memberships: type: array description: Reward opportunities per program membership. items: $ref: '#/components/schemas/ExamineRewardsMembership' object: type: string const: rewards_examine_result description: Object type marker. Always `rewards_examine_result`. required: - customer - rewards - memberships - object ErrorResponse: type: object description: Standard error response returned by all Loyalty v2 endpoints. properties: code: type: integer description: HTTP status code of the error. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional details about the error. request_id: type: string description: Unique identifier of the request that produced the error. resource_id: type: string description: Unique identifier of the resource that produced the error. resource_type: type: string description: Type of the resource that produced the error. ExamineCustomerIdentification: type: object description: >- 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`. properties: type: type: string enum: - customer_id - customer_source_id - member_id description: Identification method. customer_id: type: - string - 'null' pattern: ^cust_[a-zA-Z0-9]+ description: >- Unique customer ID (`cust_...`). Required when `type` is `customer_id`. customer_source_id: type: - string - number - 'null' description: >- 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`. member_id: type: - string - 'null' pattern: ^lmbr_[a-f0-9]+$ description: Loyalty member ID (`lmbr_...`). Required when `type` is `member_id`. required: - type additionalProperties: false allOf: - if: required: - type properties: type: const: customer_id then: required: - customer_id properties: customer_source_id: type: 'null' member_id: type: 'null' - if: required: - type properties: type: const: customer_source_id then: required: - customer_source_id properties: customer_id: type: 'null' member_id: type: 'null' - if: required: - type properties: type: const: member_id then: required: - member_id properties: customer_id: type: 'null' customer_source_id: type: 'null' Metadata: type: object description: Arbitrary key-value metadata; any JSON object is accepted. additionalProperties: true ExamineCustomerReference: type: object description: Customer reference in examine results. properties: id: type: string description: Unique customer ID (`cust_...`). source_id: type: - string - 'null' description: Customer source ID. metadata: type: object description: Customer metadata (empty object when unset). additionalProperties: true object: type: string const: customer description: Object type marker. Always `customer`. required: - id - source_id - metadata - object ExamineRewardsRewardDetail: type: object description: Reward detail. properties: id: type: string description: Unique reward ID (`lrew_...`). name: type: string description: Reward name. type: type: string enum: - MATERIAL - DIGITAL description: Reward type. metadata: type: object description: Reward metadata (empty object when unset). additionalProperties: true object: type: string const: reward description: Object type marker. Always `reward`. purchase_limits: $ref: '#/components/schemas/RewardPurchaseLimits' description: >- Purchase limits configured on the reward. Present when the reward has purchase limits configured. required: - id - name - type - metadata - object ExamineRewardsMembership: type: object description: Reward opportunities for one program membership. properties: member: $ref: '#/components/schemas/ExamineMemberReference' description: Identifies the examined loyalty program member. program: $ref: '#/components/schemas/ExamineProgramReference' description: Identifies the loyalty program for this membership. cards: type: array description: Reward estimations per card. items: $ref: '#/components/schemas/ExamineRewardsCardEstimation' object: type: string const: member_rewards_opportunity description: Object type marker. Always `member_rewards_opportunity`. required: - member - program - cards - object RewardPurchaseLimits: type: object description: >- Limits on how often a member can purchase the reward. Always present on reward responses; defaults to no cooldown and no frequency limit. properties: cooldown: $ref: '#/components/schemas/RewardPurchaseLimitsCooldown' description: Cooldown after a purchase. frequency: $ref: '#/components/schemas/RewardPurchaseLimitsFrequency' description: How many times the reward can be purchased in a period. ExamineMemberReference: type: object description: Member reference in examine results. properties: id: type: string description: Unique member ID (`lmbr_...`). customer_id: type: string description: Unique customer ID the member belongs to. program_id: type: string description: Unique program ID the member belongs to. metadata: type: object description: Member metadata (empty object when unset). additionalProperties: true object: type: string const: member description: Object type marker. Always `member`. required: - id - customer_id - program_id - metadata - object ExamineProgramReference: type: object description: Program reference in examine results. properties: id: type: string description: Unique program ID (`lprg_...`). name: type: string description: Program name. metadata: type: object description: Program metadata (empty object when unset). additionalProperties: true object: type: string description: Object type marker. Always `program`. const: program required: - id - name - metadata - object ExamineRewardsCardEstimation: type: object description: Reward estimations for a single card. properties: card: $ref: '#/components/schemas/ExamineCardReference' description: Identifies the card used for the reward estimations. rewards: type: array description: Reward availability estimations for this card. items: $ref: '#/components/schemas/ExamineRewardsCardRewardEstimation' object: type: string const: card_estimation description: Object type marker. Always `card_estimation`. required: - card - rewards - object RewardPurchaseLimitsCooldown: type: object description: Purchase cooldown limits for a reward. properties: type: type: string enum: - NO_COOLDOWN - FIXED_COOLDOWN description: >- Cooldown type. `NO_COOLDOWN` - no cooldown. `FIXED_COOLDOWN` - wait a fixed period after each purchase. fixed_cooldown: description: >- Fixed cooldown details. Present when `type` is `FIXED_COOLDOWN`; omitted or `null` for `NO_COOLDOWN`. oneOf: - $ref: '#/components/schemas/RewardPurchaseLimitsCooldownFixedCooldown' - type: 'null' required: - type RewardPurchaseLimitsFrequency: type: object description: Purchase frequency limits for a reward. properties: type: type: string enum: - NO_LIMIT - LIMITED description: >- Frequency limit type. `NO_LIMIT` - unlimited purchases. `LIMITED` - limited by the `limits` array. limits: type: array description: >- Frequency limit definitions. Empty array when `type` is `NO_LIMIT`; one entry when `type` is `LIMITED`. items: $ref: '#/components/schemas/RewardPurchaseLimitsFrequencyLimit' required: - type - limits ExamineCardReference: type: object description: Card reference in examine results. properties: id: type: string description: Unique card ID (`lcrd_...`). card_definition_id: type: string description: Unique card definition ID (`lcdef_...`). card_type: type: string enum: - INDIVIDUAL description: Card type. Currently only `INDIVIDUAL` exists. code: type: - string - 'null' description: >- Card code. May be `null` right after member creation because card codes are generated asynchronously. object: type: string const: card description: Object type marker. Always `card`. required: - id - card_definition_id - card_type - code - object ExamineRewardsCardRewardEstimation: type: object description: Reward availability estimation for a card. properties: reward: $ref: '#/components/schemas/ExamineRewardsRewardReference' description: Identifies the examined reward. status: type: string enum: - AVAILABLE - UNAVAILABLE description: Whether the reward can currently be obtained with this card. cost: $ref: '#/components/schemas/ExamineRewardsRewardCost' description: Provides the matched points cost for this card. unavailability_reasons: type: array description: >- Reasons the reward is unavailable. Absent when the reward is available. items: $ref: '#/components/schemas/ExamineRewardsRewardUnavailabilityReason' object: type: string const: reward_estimation description: Object type marker. Always `reward_estimation`. required: - reward - status - cost - object RewardPurchaseLimitsCooldownFixedCooldown: type: object description: Fixed cooldown configuration. properties: period: $ref: '#/components/schemas/RewardPurchaseLimitsCooldownFixedCooldownPeriod' description: Cooldown period. required: - period RewardPurchaseLimitsFrequencyLimit: type: object description: A frequency limit. Currently only `TIME_BASED` is supported. properties: type: type: string const: TIME_BASED description: Limit type. Always `TIME_BASED`. period: $ref: '#/components/schemas/CardDefinitionLimitTimeBasedPeriod' description: >- Time period that resets the purchase counter. Reuses the card-definition time-based period shape. triggers: $ref: '#/components/schemas/RewardPurchaseLimitsFrequencyLimitTriggers' description: Purchase count limit within the period. required: - type - period - triggers ExamineRewardsRewardReference: type: object description: Reward reference. properties: id: type: string description: Unique reward ID (`lrew_...`). object: type: string const: reward description: Object type marker. Always `reward`. required: - id - object ExamineRewardsRewardCost: type: object description: Reward cost. properties: points: type: number description: Points cost of the reward for this card. object: type: string const: reward_cost description: Object type marker. Always `reward_cost`. required: - points - object ExamineRewardsRewardUnavailabilityReason: type: object description: Reason a reward is unavailable. properties: reason: type: string enum: - insufficient_balance - no_target_card description: >- 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: description: Provides values related to the unavailability reason. oneOf: - type: object title: Insufficient balance description: Provides balance details for `insufficient_balance`. additionalProperties: false properties: required: type: number description: >- Points required to obtain the reward (reward price in points). available: type: number description: Points available on the source card. missing: type: number description: Additional points required to obtain the reward. required: - required - available - missing - type: object description: Identifies the missing target card for `no_target_card`. title: No target card additionalProperties: false properties: card_definition_id: type: string description: >- Unique card definition ID (`lcdef_...`) of the missing target card. required: - card_definition_id object: type: string const: reward_unavailability_reason description: Object type marker. Always `reward_unavailability_reason`. required: - reason - details - object RewardPurchaseLimitsCooldownFixedCooldownPeriod: type: object description: Fixed cooldown period after a reward purchase. properties: value: type: integer description: Length of the cooldown period. minimum: 1 unit: type: string enum: - HOUR - DAY - WEEK - MONTH - YEAR description: Unit of the cooldown period. required: - value - unit CardDefinitionLimitTimeBasedPeriod: type: object description: Time-based limit period. properties: type: type: string enum: - CURRENT_PERIOD description: Period type. current_period: type: object description: >- Current-period configuration. Present when `type` is `CURRENT_PERIOD`. properties: unit: type: string enum: - DAY - WEEK - MONTH - QUARTER - YEAR description: Calendar period unit. required: - unit required: - type RewardPurchaseLimitsFrequencyLimitTriggers: type: object description: Maximum number of purchases allowed in the period. properties: max: type: integer minimum: 1 description: Maximum number of purchases in the configured period. required: - max securitySchemes: X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header bearerAuth: type: http scheme: bearer bearerFormat: JWT ````