--- title: "Purchase a reward with points" method: POST path: "/v2/loyalties/programs/{programId}/members/{memberId}/rewards/purchases" tags: ["Programs"] --- # Purchase a reward with points `POST /v2/loyalties/programs/{programId}/members/{memberId}/rewards/purchases` ## Request - Base URL: `https://api.voucherify.io` - URL: `https://api.voucherify.io/v2/loyalties/programs/{programId}/members/{memberId}/rewards/purchases` - Auth: none required 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](https://www.voucherify.io/contact-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. ## Path parameters - `programId` string, required - `memberId` string, required ## Request body - RewardPurchaseCreateRequest: Request body for purchasing a reward with points. - `reward_id` string, required: Identifier of the reward to purchase (format `lrew_...`). - `mode` 'TRANSACTION' | 'DRY_RUN': 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. ## Response `200` Dry run result (mode `DRY_RUN`). No transaction was created; the returned transaction has status SIMULATED and no `id`. - RewardPurchaseCreateResponse: Result of a reward purchase request. - `transaction` RewardPurchaseTransaction: A reward transaction. Represents a reward purchase or a reward refund. - `id` string: Unique reward transaction identifier (format `lrtx_...`). Absent for DRY_RUN (SIMULATED) transactions, which are never persisted. - `card_id` string: Identifier of the loyalty card the points were spent from (format `lcrd_...`). - `card_transaction_id` unknown - `program_id` string: Identifier of the loyalty program (format `lprg_...`). - `member_id` string: Identifier of the program member (format `lmbr_...`). - `reward_id` string: Identifier of the purchased reward (format `lrew_...`). - `status` 'PENDING' | 'PROCESSING' | 'APPROVED' | 'REJECTED' | 'SIMULATED' | 'REFUNDED': 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` 'PURCHASE' | 'REFUND': Transaction type. - `details` union: Transaction details. Shape depends on `type` — purchase details for `PURCHASE`, refund details for `REFUND`. - RewardPurchaseTransactionDetailsPurchase: Details of a PURCHASE reward transaction. - `reason` string: Human-readable reason. For purchases: "Points spent on reward". - `rejection` RewardPurchaseRejection: Rejection details. - `reason` string: Machine-readable rejection reason. - `details` string: Additional human-readable details about the rejection. - `metadata` object: Transaction metadata. Empty object when not set. - `points` RewardPurchasePoints: Points involved in the transaction. - `total` number: Total number of points. - `result` RewardPurchaseResult: Reward fulfillment result. Contains the fulfilled reward reference, quantity and the material or digital fulfillment payload. - `reward` RewardPurchaseResultReward: Reference to the fulfilled reward. - `id` string: Reward identifier (format `lrew_...`). - `type` 'MATERIAL' | 'DIGITAL': Reward type. - `quantity` unknown - `material` RewardPurchaseResultMaterial: Material reward fulfillment. - `type` 'PRODUCT' | 'SKU': Material reward type. - `product` object: Product payload (present when `type` is `PRODUCT`). - `sku` object: SKU payload (present when `type` is `SKU`). - `digital` RewardPurchaseResultDigital: Digital reward fulfillment. - `type` 'DISCOUNT_COUPONS' | 'GIFT_VOUCHERS' | 'LOYALTY_CARD_POINTS': Digital reward type. - `discount_coupons` RewardPurchaseDigitalCoupon[]: Fulfilled discount coupons (present when `type` is `DISCOUNT_COUPONS`). - … - `gift_vouchers` RewardPurchaseDigitalGiftVoucher[]: Fulfilled gift vouchers (present when `type` is `GIFT_VOUCHERS`). - … - `loyalty_card_points` RewardPurchaseDigitalLoyaltyCardPoints: Loyalty card points fulfillment entry. - … - RewardPurchaseTransactionDetailsRefund: Details of a REFUND reward transaction. - `reason` string: Human-readable reason, e.g. "Reward refund — point purchase reversed". - `rejection` RewardPurchaseRejection: Rejection details. - `reason` string: Machine-readable rejection reason. - `details` string: Additional human-readable details about the rejection. - `metadata` object: Transaction metadata. Empty object when not set. - `points` RewardPurchasePoints: Points involved in the transaction. - `total` number: Total number of points. - `result` RewardPurchaseResult: Reward fulfillment result. Contains the fulfilled reward reference, quantity and the material or digital fulfillment payload. - `reward` RewardPurchaseResultReward: Reference to the fulfilled reward. - `id` string: Reward identifier (format `lrew_...`). - `type` 'MATERIAL' | 'DIGITAL': Reward type. - `quantity` unknown - `material` RewardPurchaseResultMaterial: Material reward fulfillment. - `type` 'PRODUCT' | 'SKU': Material reward type. - `product` object: Product payload (present when `type` is `PRODUCT`). - `sku` object: SKU payload (present when `type` is `SKU`). - `digital` RewardPurchaseResultDigital: Digital reward fulfillment. - `type` 'DISCOUNT_COUPONS' | 'GIFT_VOUCHERS' | 'LOYALTY_CARD_POINTS': Digital reward type. - `discount_coupons` RewardPurchaseDigitalCoupon[]: Fulfilled discount coupons (present when `type` is `DISCOUNT_COUPONS`). - … - `gift_vouchers` RewardPurchaseDigitalGiftVoucher[]: Fulfilled gift vouchers (present when `type` is `GIFT_VOUCHERS`). - … - `loyalty_card_points` RewardPurchaseDigitalLoyaltyCardPoints: Loyalty card points fulfillment entry. - … - `purchase` RewardPurchaseRefundPurchaseReference: References to the original purchase transactions being refunded. - `card_transaction` object: Reference to the original card transaction. - `id` string: Card transaction identifier (format `lctx_...`). - `reward_transaction` object: Reference to the original reward transaction. - `id` string: Reward transaction identifier (format `lrtx_...`). - `created_at` string, date-time: Timestamp when the transaction was created (ISO 8601). - `updated_at` string, date-time: Timestamp when the transaction was last updated (ISO 8601), or `null`. - `object` string: Object type marker. Always `reward_transaction`. - `status` 'TRANSACTION_CREATED' | 'DRY_RUN': Result status. `TRANSACTION_CREATED` for `TRANSACTION` mode, `DRY_RUN` for dry-run mode. - `message` string: 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.". ## Other responses - `202`: Purchase accepted (mode `TRANSACTION`). A PENDING reward transaction was created and will be processed asynchronously. - `400`: Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state. - `404`: Resource not found. - `409`: Conflict - e.g. duplicate resource or invalid state transition. - `500`: Internal server error. --- [API](https://skmtc.dev/voucherifyio/apis/voucherify-api-async-actions.md) - [All operations](https://skmtc.dev/voucherifyio/apis/voucherify-api-async-actions/llms.txt) - [OpenAPI document](https://skmtc.dev/voucherifyio/apis/voucherify-api-async-actions/revisions/4982266e0494?raw)