> ## Documentation Index > Fetch the complete documentation index at: https://voucherify-rc-lv2-guides.mintlify.site/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. Use `member_id` to examine one membership only. Applies temporary customer and member metadata overrides without updating stored data. Returns reward availability by card, including points costs and applicable unavailability reasons. ## 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, 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. Use `member_id` to examine one membership only. Applies temporary customer and member metadata overrides without updating stored data. Returns reward availability by card, including points costs and applicable unavailability reasons. 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 - id: lrew_128f4c6710947c85d1 name: Minas Gerais 500 type: MATERIAL metadata: {} object: reward - id: lrew_1294cebb458e4904a0 name: Carioca shirt type: MATERIAL metadata: {} object: reward - id: lrew_12b22d6ef31184e002 name: Carioca shorts type: MATERIAL metadata: {} object: reward - id: lrew_12bb65405edf8d3dec name: Carioca longsleeve type: MATERIAL metadata: {} object: reward 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. 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 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`. 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 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 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 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 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 ````