> ## 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. # Purchase a reward with points > ⚠️ **BETA endpoint** This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager. Purchases a reward on behalf of the program member, spending points from the member's loyalty card (the card is resolved from the reward cost's card definition). Requires an ACTIVE program, an ACTIVE member, an ACTIVE reward 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: - bearerAuth: [] X-App-Id: [] X-App-Token: [] 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), 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: post: tags: - Programs summary: Purchase a reward with points description: > ⚠️ **BETA endpoint** This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager. Purchases a reward on behalf of the program member, spending points from the member's loyalty card (the card is resolved from the reward cost's card definition). Requires an ACTIVE program, an ACTIVE member, an ACTIVE reward 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: - 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]+$ 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/RewardPurchaseCreateResponse' '202': description: > Purchase accepted (mode `TRANSACTION`). A PENDING reward transaction was created and will be processed asynchronously. content: application/json: schema: $ref: '#/components/schemas/RewardPurchaseCreateResponse' '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' '409': description: Conflict - e.g. duplicate resource or invalid state transition. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '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: 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 RewardPurchaseCreateResponse: type: object description: | Result of a reward purchase request. properties: transaction: description: The created (or simulated) reward transaction. oneOf: - $ref: '#/components/schemas/RewardPurchaseTransaction' - type: 'null' status: type: string enum: - TRANSACTION_CREATED - DRY_RUN description: > Result status. `TRANSACTION_CREATED` for `TRANSACTION` mode, `DRY_RUN` for dry-run mode. message: type: string description: > Human-readable result message. `TRANSACTION` mode: "Reward purchase transaction created". `DRY_RUN` mode: "Dry run mode. No transaction was created. This is only a simulation.". 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: Identifier of the request that produced the error. RewardPurchaseTransaction: type: object description: | A reward transaction. Represents a reward purchase or a reward refund. properties: id: type: string description: > Unique reward transaction identifier (format `lrtx_...`). Absent for DRY_RUN (SIMULATED) transactions, which are never persisted. card_id: type: string description: >- Identifier of the loyalty card the points were spent from (format `lcrd_...`). card_transaction_id: type: - string - 'null' description: > Identifier of the underlying card transaction (format `lctx_...`). `null` for DRY_RUN (SIMULATED) transactions. program_id: type: string description: Identifier of the loyalty program (format `lprg_...`). member_id: type: string description: Identifier of the program member (format `lmbr_...`). reward_id: type: string description: Identifier of the purchased reward (format `lrew_...`). status: type: string enum: - PENDING - PROCESSING - APPROVED - REJECTED - SIMULATED - REFUNDED description: > Transaction status. `PENDING` — created, awaiting processing; `PROCESSING` — being processed; `APPROVED` — completed successfully; `REJECTED` — rejected (see `details.rejection`); `SIMULATED` — dry-run result, not persisted; `REFUNDED` — purchase has been refunded. type: type: string enum: - PURCHASE - REFUND description: Transaction type. details: description: > Transaction details. Shape depends on `type` — purchase details for `PURCHASE`, refund details for `REFUND`. oneOf: - $ref: '#/components/schemas/RewardPurchaseTransactionDetailsPurchase' - $ref: '#/components/schemas/RewardPurchaseTransactionDetailsRefund' - 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`. RewardPurchaseTransactionDetailsPurchase: type: object 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. 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' RewardPurchaseTransactionDetailsRefund: type: object description: | Details of a REFUND reward transaction. properties: reason: type: string description: >- Human-readable reason, e.g. "Reward refund — point purchase reversed". rejection: description: Rejection details, present when the transaction was rejected. oneOf: - $ref: '#/components/schemas/RewardPurchaseRejection' - type: 'null' metadata: type: object description: Transaction metadata. Empty object when not set. additionalProperties: true points: description: Points returned by the refund. oneOf: - $ref: '#/components/schemas/RewardPurchasePoints' - type: 'null' result: description: Refunded reward result (what was reverted). oneOf: - $ref: '#/components/schemas/RewardPurchaseResult' - type: 'null' purchase: description: References to the refunded purchase transactions. oneOf: - $ref: '#/components/schemas/RewardPurchaseRefundPurchaseReference' - type: 'null' RewardPurchaseRejection: type: object description: Rejection details. properties: reason: type: string description: Machine-readable rejection reason. details: type: string description: Additional human-readable details about the rejection. RewardPurchasePoints: type: object description: Points involved in the transaction. properties: total: type: number description: Total number of points. 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' RewardPurchaseRefundPurchaseReference: type: object description: References to the original purchase transactions being refunded. properties: card_transaction: description: Reference to the original card transaction. oneOf: - type: object properties: id: type: string description: Card transaction identifier (format `lctx_...`). - type: 'null' reward_transaction: description: Reference to the original reward transaction. oneOf: - type: object properties: id: type: string description: Reward transaction identifier (format `lrtx_...`). - 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 - CREDITS_SUBTRACTED 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 - DELETED - 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: bearerAuth: type: http scheme: bearer bearerFormat: JWT X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header ````