> ## 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. # Purchase a reward with points > Purchases a reward on behalf of the program member by spending points from the member's loyalty card (the card is resolved from the reward cost's card definition). Requires an `ACTIVE` program and an `ACTIVE` reward within their configured validity windows, an `ACTIVE` member, the reward to be assigned to the program with available stock, a matching reward cost for the customer's context, and sufficient points within the configured spending limits. Modes: - `TRANSACTION` (default): creates a `PENDING` reward transaction (and an underlying card transaction) processed asynchronously. Returns HTTP `202`. - `DRY_RUN`: simulates the purchase without creating any transaction. Returns HTTP `200` with a `SIMULATED` transaction payload. ## OpenAPI ````yaml /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/{memberId}/rewards/purchases 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/programs/{programId}/members/{memberId}/rewards/purchases: parameters: - name: programId in: path required: true description: >- Unique loyalty program identifier (format: `lprg_` followed by hexadecimal characters). schema: type: string - name: memberId in: path required: true description: Program member ID (format `lmbr_[a-f0-9]+`). schema: type: string pattern: ^lmbr_[a-f0-9]+$ post: tags: - Programs summary: Purchase a reward with points description: >- Purchases a reward on behalf of the program member by spending points from the member's loyalty card (the card is resolved from the reward cost's card definition). Requires an `ACTIVE` program and an `ACTIVE` reward within their configured validity windows, an `ACTIVE` member, the reward to be assigned to the program with available stock, a matching reward cost for the customer's context, and sufficient points within the configured spending limits. Modes: - `TRANSACTION` (default): creates a `PENDING` reward transaction (and an underlying card transaction) processed asynchronously. Returns HTTP `202`. - `DRY_RUN`: simulates the purchase without creating any transaction. Returns HTTP `200` with a `SIMULATED` transaction payload. operationId: purchaseMemberReward parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RewardPurchaseCreateRequest' responses: '200': description: >- Dry run result (mode `DRY_RUN`). No transaction was created; the returned transaction has status `SIMULATED` and no `id`. content: application/json: schema: $ref: '#/components/schemas/RewardPurchaseCreateDryRunResponse' examples: Reward purchase dry run: value: transaction: card_id: lcrd_128f962dbd8c4ba5e1 card_transaction_id: null program_id: lprg_128f58429f4c4bf7b2 member_id: lmbr_128f962dbc8c4ba5dc reward_id: lrew_1294cebb458e4904a0 status: SIMULATED type: PURCHASE details: reason: Points spent on reward rejection: null metadata: {} points: total: 500 result: null updated_at: null object: reward_transaction status: DRY_RUN message: >- Dry run mode. No transaction was created. This is only a simulation. '202': description: >- Purchase accepted (mode `TRANSACTION`). A `PENDING` reward transaction was created and will be processed asynchronously. content: application/json: schema: $ref: '#/components/schemas/RewardPurchaseCreateTransactionResponse' examples: Reward purchase transaction created: value: transaction: id: lrtx_12cad1abefa2311e03 card_id: lcrd_128f962dbd8c4ba5e1 card_transaction_id: lctx_12cad1abefa2311e02 program_id: lprg_128f58429f4c4bf7b2 member_id: lmbr_128f962dbc8c4ba5dc reward_id: lrew_1294cebb458e4904a0 status: PENDING type: PURCHASE details: reason: Points spent on reward rejection: null metadata: {} points: total: 500 result: null created_at: '2026-07-27T16:09:59.999Z' updated_at: null object: reward_transaction status: TRANSACTION_CREATED message: Reward purchase transaction created '400': description: Request body validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Member not found: value: code: 404 key: not_found message: Resource not found details: Cannot find member with id lmbr_128f96dbc8c4ba5dc request_id: v-12cbaf63ce6ac91da3 resource_id: lmbr_128f96dbc8c4ba5dc resource_type: member Program not found: value: code: 404 key: not_found message: Resource not found details: Cannot find program with id lprg_128f5429f4c4bf7b2 request_id: v-12cbaf431280295102 resource_id: lprg_128f5429f4c4bf7b2 resource_type: program Reward not found: value: code: 404 key: not_found message: Resource not found details: Cannot find reward with id lrew_128f4cefbad47863e request_id: v-12cbaf831680295186 resource_id: lrew_128f4cefbad47863e resource_type: reward '423': description: >- The purchase is unavailable because a resource state, validity window, stock level, matching cost, card balance, or spending limit prevents it. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Insufficient card balance: value: code: 423 key: insufficient_card_balance message: Insufficient card balance details: Operation exceeds the available card balance request_id: v-12cbb8e7c89a39f4df Reward out of stock: value: code: 423 key: reward_out_of_stock message: Cannot purchase reward when stock is not available details: Reward stock is not available request_id: v-12cbaf9b78002951b5 '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: RewardPurchaseCreateRequest: type: object description: Request body for purchasing a reward with points. properties: reward_id: type: string description: Unique identifier of the reward to purchase (format `lrew_...`). mode: type: string enum: - TRANSACTION - DRY_RUN default: TRANSACTION description: >- Purchase mode. `TRANSACTION` creates a `PENDING` reward transaction processed asynchronously (HTTP `202`). `DRY_RUN` only simulates the purchase and returns the calculation result (HTTP `200`); no transaction is created. Defaults to `TRANSACTION` when omitted. required: - reward_id additionalProperties: false RewardPurchaseCreateDryRunResponse: type: object description: Result of a reward purchase request in dry-run mode. properties: transaction: type: object description: The simulated reward transaction. properties: card_id: type: string description: >- Unique identifier of the loyalty card the points are to be spent from (format `lcrd_...`). card_transaction_id: type: 'null' description: '`null` for `DRY_RUN` (SIMULATED) transactions.' program_id: type: string description: Unique identifier of the loyalty program (format `lprg_...`). member_id: type: string description: Unique identifier of the program member (format `lmbr_...`). reward_id: type: string description: Unique identifier of the purchased reward (format `lrew_...`). status: type: string enum: - SIMULATED description: >- Transaction status is `SIMULATED` for a dry-run result that is not persisted. type: type: string const: PURCHASE description: >- Transaction type. It contains purchase details for the simulated transaction. details: $ref: '#/components/schemas/RewardPurchaseTransactionDetailsPurchase' description: >- Transaction details. For a dry run purchase, it's always `PURCHASE`. updated_at: type: 'null' description: For `DRY_RUN` transactions, this is always `null`. object: type: string const: reward_transaction description: Object type marker. Always `reward_transaction`. required: - id - card_id - card_transaction_id - program_id - member_id - reward_id - status - type - details - created_at - updated_at - object status: type: string enum: - DRY_RUN description: Result status. Always `DRY_RUN` for the dry-run mode. message: type: string description: >- Human-readable result message. `DRY_RUN` mode: "Dry run mode. No transaction was created. This is only a simulation.". required: - transaction - status - message RewardPurchaseCreateTransactionResponse: type: object description: Result of a reward purchase request. properties: transaction: type: object description: A reward transaction. Represents a reward purchase transaction. properties: id: type: string description: Unique reward transaction identifier (format `lrtx_...`). card_id: type: string description: >- Unique identifier of the loyalty card the points were spent from (format `lcrd_...`). card_transaction_id: type: string description: >- Unique identifier of the underlying card transaction (format `lctx_...`). program_id: type: string description: Unique identifier of the loyalty program (format `lprg_...`). member_id: type: string description: Unique identifier of the program member (format `lmbr_...`). reward_id: type: string description: Unique identifier of the purchased reward (format `lrew_...`). status: type: string enum: - PENDING description: |- Transaction status: - `PENDING`: Created and awaiting processing. type: type: string enum: - PURCHASE description: Transaction type. details: description: >- Transaction details. Shape depends on `type` — purchase details for `PURCHASE`. oneOf: - $ref: >- #/components/schemas/RewardPurchaseTransactionDetailsPurchase - type: 'null' created_at: type: string format: date-time description: Timestamp when the transaction was created (ISO 8601). updated_at: type: - string - 'null' format: date-time description: >- Timestamp when the transaction was last updated (ISO 8601), or `null`. object: type: string const: reward_transaction description: Object type marker. Always `reward_transaction`. required: - id - card_id - card_transaction_id - program_id - member_id - reward_id - status - type - details - created_at - updated_at - object status: type: string enum: - TRANSACTION_CREATED description: Result status. `TRANSACTION_CREATED` for `TRANSACTION` mode. message: type: string description: >- Human-readable result message. `TRANSACTION` mode: "Reward purchase transaction created". required: - transaction - status - message 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. RewardPurchaseTransactionDetailsPurchase: type: object title: Purchase details description: Details of a `PURCHASE` reward transaction. properties: reason: type: string description: 'Human-readable reason. For purchases: "Points spent on reward".' rejection: description: >- Rejection details, present when the transaction was rejected. `null` otherwise. oneOf: - $ref: '#/components/schemas/RewardPurchaseRejection' - type: 'null' metadata: type: object description: Transaction metadata. Empty object when not set. additionalProperties: true points: description: Points spent on the purchase. oneOf: - $ref: '#/components/schemas/RewardPurchasePoints' - type: 'null' result: description: >- Fulfillment result, populated once the purchase is processed (APPROVED). `null` for `PENDING`/`SIMULATED` transactions. oneOf: - $ref: '#/components/schemas/RewardPurchaseResult' - type: 'null' required: - reason - rejection - metadata - points - result RewardPurchaseRejection: type: object description: Details about a rejected reward purchase transaction. properties: reason: type: string description: Machine-readable rejection reason. details: type: object description: >- Additional structured context about the rejection. Fields depend on the rejection reason. additionalProperties: true required: - reason RewardPurchasePoints: type: object description: Points involved in the transaction. properties: total: type: number description: Total number of points. required: - total RewardPurchaseResult: type: object description: >- Reward fulfillment result. Contains the fulfilled reward reference, quantity and the material or digital fulfillment payload. properties: reward: description: Reference to the fulfilled reward. oneOf: - $ref: '#/components/schemas/RewardPurchaseResultReward' - type: 'null' quantity: type: - number - 'null' description: Fulfilled quantity. material: description: Material reward fulfillment payload. Present for `MATERIAL` rewards. oneOf: - $ref: '#/components/schemas/RewardPurchaseResultMaterial' - type: 'null' digital: description: Digital reward fulfillment payload. Present for `DIGITAL` rewards. oneOf: - $ref: '#/components/schemas/RewardPurchaseResultDigital' - type: 'null' RewardPurchaseResultReward: type: object description: Reference to the fulfilled reward. properties: id: type: string description: Reward identifier (format `lrew_...`). type: type: string enum: - MATERIAL - DIGITAL description: Reward type. RewardPurchaseResultMaterial: type: object description: Material reward fulfillment. properties: type: type: string enum: - PRODUCT - SKU description: Material reward type. product: type: object description: Product payload (present when `type` is `PRODUCT`). additionalProperties: true sku: type: object description: SKU payload (present when `type` is `SKU`). additionalProperties: true RewardPurchaseResultDigital: type: object description: Digital reward fulfillment. properties: type: type: string enum: - DISCOUNT_COUPONS - GIFT_VOUCHERS - LOYALTY_CARD_POINTS description: Digital reward type. discount_coupons: type: array description: >- Fulfilled discount coupons (present when `type` is `DISCOUNT_COUPONS`). items: $ref: '#/components/schemas/RewardPurchaseDigitalCoupon' gift_vouchers: type: array description: Fulfilled gift vouchers (present when `type` is `GIFT_VOUCHERS`). items: $ref: '#/components/schemas/RewardPurchaseDigitalGiftVoucher' loyalty_card_points: description: >- Fulfilled loyalty card points (present when `type` is `LOYALTY_CARD_POINTS`). oneOf: - $ref: '#/components/schemas/RewardPurchaseDigitalLoyaltyCardPoints' - type: 'null' RewardPurchaseDigitalCoupon: type: object description: Discount coupon fulfillment entry. properties: id: type: string description: Voucher identifier of the coupon. code: type: string description: Coupon code. result: type: string enum: - SKIPPED - DELETED description: |- Refund handling result for this coupon (present in refund results): - `DELETED`: The coupon was deleted. - `SKIPPED`: The coupon was left intact. RewardPurchaseDigitalGiftVoucher: type: object description: Gift voucher fulfillment entry. properties: id: type: string description: Voucher identifier of the gift voucher. code: type: string description: Gift voucher code. amount: type: number description: >- Amount added to (or, for refunds, subtracted from) the gift voucher balance. balance: type: number description: Gift voucher balance after the operation. result: type: string enum: - SKIPPED - CREDITS_SUBTRACTED description: >- Refund handling result for this gift voucher (present in refund results): - `CREDITS_SUBTRACTED`: The credited balance was subtracted. - `SKIPPED`: The voucher was left intact. RewardPurchaseDigitalLoyaltyCardPoints: type: object description: Loyalty card points fulfillment entry. properties: points: type: number description: Number of points credited to the target loyalty card. card_definition_id: type: string description: Target card definition identifier (format `lcdef_...`). card_id: type: string description: Target loyalty card identifier (format `lcrd_...`). 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 ````