---
title: "Purchase reward with points"
method: POST
path: "/v2/loyalties/programs/{programId}/members/{memberId}/rewards/purchases"
tags: ["Programs"]
---

# Purchase reward with points

`POST /v2/loyalties/programs/{programId}/members/{memberId}/rewards/purchases`

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.

## Request body

- RewardPurchaseCreateRequest — Request body for purchasing a reward with points.
  - `reward_id` string, required — Unique 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`.

- RewardPurchaseCreateDryRunResponse — Result of a reward purchase request in dry-run mode.
  - `transaction` object, required — The simulated reward transaction.
    - `card_id` string, required — Unique identifier of the loyalty card the points are to be spent from (format `lcrd_...`).
    - `card_transaction_id` unknown, required
    - `program_id` string, required — Unique identifier of the loyalty program (format `lprg_...`).
    - `member_id` string, required — Unique identifier of the program member (format `lmbr_...`).
    - `reward_id` string, required — Unique identifier of the purchased reward (format `lrew_...`).
    - `status` 'SIMULATED', required — Transaction status is `SIMULATED` for a dry-run result that is not persisted.
    - `type` 'PURCHASE', required — Transaction type. It contains purchase details for the simulated transaction.
    - `details` RewardPurchaseTransactionDetailsPurchase, required — Details of a `PURCHASE` reward transaction.
      - `reason` string, required — Human-readable reason. For purchases: "Points spent on reward".
      - `rejection` RewardPurchaseRejection, required — Details about a rejected reward purchase transaction.
        - `reason` string, required — Machine-readable rejection reason.
        - `details` object — Additional structured context about the rejection. Fields depend on the rejection reason.
      - `metadata` object, required — Transaction metadata. Empty object when not set.
      - `points` RewardPurchasePoints, required — Points involved in the transaction.
        - `total` number, required — Total number of points.
      - `result` RewardPurchaseResult, required — 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` number, nullable — Fulfilled quantity.
        - `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`).
            - `id` string — Voucher identifier of the coupon.
            - `code` string — Coupon code.
            - `result` 'SKIPPED' | 'DELETED' — Refund handling result for this coupon (present in refund results): - `DELETED`: The coupon was deleted. - `SKIPPED`: The coupon was left intact.
          - `gift_vouchers` RewardPurchaseDigitalGiftVoucher[] — Fulfilled gift vouchers (present when `type` is `GIFT_VOUCHERS`).
            - `id` string — Voucher identifier of the gift voucher.
            - `code` string — Gift voucher code.
            - `amount` number — Amount added to (or, for refunds, subtracted from) the gift voucher balance.
            - `balance` number — Gift voucher balance after the operation.
            - `result` 'SKIPPED' | 'CREDITS_SUBTRACTED' — Refund handling result for this gift voucher (present in refund results): - `CREDITS_SUBTRACTED`: The credited balance was subtracted. - `SKIPPED`: The voucher was left intact.
          - `loyalty_card_points` RewardPurchaseDigitalLoyaltyCardPoints — Loyalty card points fulfillment entry.
            - `points` number — Number of points credited to the target loyalty card.
            - `card_definition_id` string — Target card definition identifier (format `lcdef_...`).
            - `card_id` string — Target loyalty card identifier (format `lcrd_...`).
    - `updated_at` unknown, required
    - `object` 'reward_transaction', required — Object type marker. Always `reward_transaction`.
  - `status` 'DRY_RUN', required — Result status. Always `DRY_RUN` for the dry-run mode.
  - `message` string, required — Human-readable result message. `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` — Request body validation failed.
- `404` — Resource not found.
- `423` — The purchase is unavailable because a resource state, validity window, stock level, matching cost, card balance, or spending limit prevents it.
- `500` — Internal server error.

---

[API](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-loyalty-v2-api/revisions/69be73b5cff0/schema)