---
title: "POST /v2/customers/{merchant_id}/claimed_rewards"
method: POST
path: "/v2/customers/{merchant_id}/claimed_rewards"
tags: ["customers"]
---

# POST /v2/customers/{merchant_id}/claimed_rewards

`POST /v2/customers/{merchant_id}/claimed_rewards`

## Request

- Base URL: `https://api.loyaltylion.com`
- URL: `https://api.loyaltylion.com/v2/customers/{merchant_id}/claimed_rewards`
- Auth: one of:
  - HTTP bearer
  - HTTP basic

## Path parameters

- `merchant_id` string, required

## Request body

- CustomersClaimRewardForCustomerRequestBody
  - `reward_id` number, required: The ID of the reward to claim
  - `multiplier` number: The number of times to claim this reward in a single request. Only supported for `store_fulfilment` custom rewards, where it must be a whole number, and for checkout redemption rewards, where it is the discount amount and must be between the reward's minimum and maximum redemption amounts, and one of its fixed redemption amounts when it has them. Other rewards reject any multiplier other than 1.
  - `variant_id` string: The Shopify variant being claimed. Required when the reward is a seamless product reward
  - `shopify_action_id` string
  - `attribution` 'redemption_notification'
  - `session` object
    - `kind` 'cart' | 'checkout', required
    - `token` string

## Response `201`

201

- CustomersClaimRewardForCustomerResponseBody
  - `claimed_reward` object, required
    - `id` number, required
    - `claimed_at` string, required: `ISO 8601` timestamp indicating when this reward was claimed
    - `point_cost` number, required: The number of points it cost to claim this reward
    - `redeemable` union, required
      - object
        - `redeemable_type` 'fulfilment', required
        - `fulfilled` boolean, required: Indicates if this reward has been fulfilled
        - `fulfilled_at` string, nullable, required: An ISO8601 timestamp representing when the reward was fulfilled, or `null` if it is not yet fulfilled
        - `expires_on` unknown, required
      - object
        - `redeemable_type` 'pos_action', required
        - `discount_amount` number, required
        - `expires_on` unknown, required
      - object
        - `redeemable_type` 'product', required
        - `product` object, required: Information about the product that was redeemed
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `sort_key` number
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
        - `used_at` string, nullable, required: An ISO 8601 timestamp representing when the product was used
        - `shopify_cart_line_item_context` string: If this product was redeemed via a Shopify Script, this will contain the context string that will be added to line item in the cart as a `__lion_context` property
        - `grant` object, nullable, required: Present when the customer was granted this product and has since added it to their cart. `null` for a product the customer redeemed with points or claimed directly
          - `expires_on` string, nullable, required: ISO 8601 timestamp of the deadline the grant had for adding the product to the cart, or `null` if the grant had no deadline
        - `expires_on` unknown, required
      - object
        - `redeemable_type` 'product_grant', required
        - `products` object[], required: The variants the shopper can add the free product to their cart as, in the reward's own order
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `sort_key` number
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
        - `expires_on` string, nullable, required: ISO 8601 timestamp by which the shopper must add the product to their cart, or `null` if the grant does not expire. Also `null` while the claim is `pending`, as the deadline is set when the trigger approves
      - object
        - `redeemable_type` 'gift_card', required
        - `code` string, nullable, required: The full gift card code. Depending on the context of the API call, this may be `null`
        - `last_characters` string, required: The last few characters of the gift card code
        - `currency` string, required: ISO 4217 currency code representing the gift card currency, e.g. `usd`
        - `balance` number, required: The current balance on the gift card
        - `initial_value` number, required: The initial balance of the gift card
        - `expires_on` string, nullable, required: ISO 8601 timestamp representing when the gift card will expire, or `null` if it does not expire
      - object
        - `redeemable_type` 'voucher', required
        - `code` string, required: The voucher/coupon code that can be applied to a cart
        - `discount_amount` number, required: The discount amount that will be applied to the cart. For flat-rate vouchers, this will be an integer value representing the discount in the primary currency, e.g. $5 will be 5. For percentage vouchers, it will be the percentage discount from 1-100
        - `usage_count` number, required: The number of times this voucher has been applied. Some voucher types, such as subscription vouchers, may be used multiple times.
        - `usage_limit` number, required: The maximum number of times this voucher may be applied
        - `used_at` string, nullable, required: An ISO 8601 timestamp representing when the voucher was used. If the voucher has been used more than once, this will be the most recent usage
        - `expires_on` string, nullable, required: ISO 8601 timestamp representing when the voucher will expire, or `null` if it does not expire
      - object
        - `redeemable_type` 'tiktok_coupon', required
        - `expires_on` unknown, required
    - `reward` union, required
      - object
        - `id` number, required
        - `title` string, required
        - `title_template` string, nullable, required
        - `description` string, nullable, required
        - `sort_key` number, required
        - `content` object, required
        - `point_cost` number, required
        - `method` 'voucher', required
        - `discount_type` 'flat' | 'percentage', required
        - `discount_amount` number, required
        - `minimum_spend` number, nullable, required
        - `usage_limit` number, required
        - `min_redemption_amount` 1, required
        - `max_redemption_amount` 1, required
        - `max_free_shipping` unknown, required
        - `site_id` number, required
        - `target_site` object, required
          - `id` number, required
          - `name` string, required
          - `url` string, required
        - `order_type` 'subscription', required
        - `target_type` 'all', required
        - `target_collections` object[], required
          - `id` union
            - number
            - string
          - `url` string
          - `restriction_text` string
        - `target_products` object[], required
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
          - `sort_key` number, required
        - `session_options` unknown, required
        - `auto_refund_seconds` unknown, required
        - `expiry_options` object, required
          - `kind` 'does_not_expire', required
          - `seconds` unknown, required
        - `redeemable_expiry_options` unknown, required
        - `supported_channels` string[], required
        - `available_countries` string[], nullable, required
        - `kind` 'active_subscription_discount_voucher', required
        - `recurring_cycle_limit` number, nullable, required
      - object
        - `id` number, required
        - `title` string, required
        - `title_template` string, nullable, required
        - `description` string, nullable, required
        - `sort_key` number, required
        - `content` object, required
          - `featured_image_url` string, nullable
        - `point_cost` number, required
        - `method` 'buy_with_points' | 'function', required
        - `discount_type` 'percentage', required
        - `discount_amount` number, required
        - `minimum_spend` number, nullable, required
        - `usage_limit` 1, required
        - `min_redemption_amount` 1, required
        - `max_redemption_amount` 1, required
        - `max_free_shipping` unknown, required
        - `site_id` number, required
        - `target_site` object, required
          - `id` number, required
          - `name` string, required
          - `url` string, required
        - `order_type` 'all', required
        - `target_type` 'product', required
        - `target_collections` object[], required
          - `id` union
            - number
            - string
          - `url` string
          - `restriction_text` string
        - `target_products` object[], required
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
          - `sort_key` number, required
        - `session_options` object, required
          - `kind` 'cart', required
          - `session_limit` 1, nullable, required
        - `auto_refund_seconds` number, required
        - `expiry_options` object, required
          - `kind` 'duration', required
          - `seconds` number, required
        - `redeemable_expiry_options` unknown, required
        - `supported_channels` string[], required
        - `available_countries` string[], nullable, required
        - `kind` 'product_cart', required
        - `minimum_requirements` union
          - BuyWithPointsRewardMinimumRequirementsCost
            - `type` 'cost', required
            - `cost` number, required
          - BuyWithPointsRewardMinimumRequirementsQuantity
            - `type` 'quantity', required
            - `quantity` number, required
      - object
        - `id` number, required
        - `title` string, required
        - `title_template` string, nullable, required
        - `description` string, nullable, required
        - `sort_key` number, required
        - `content` object, required
        - `point_cost` number, required
        - `method` 'voucher', required
        - `discount_type` 'flat' | 'percentage', required
        - `discount_amount` number, required
        - `minimum_spend` number, nullable, required
        - `usage_limit` number, required
        - `min_redemption_amount` 1, required
        - `max_redemption_amount` 1, required
        - `max_free_shipping` unknown, required
        - `site_id` number, required
        - `target_site` object, required
          - `id` number, required
          - `name` string, required
          - `url` string, required
        - `order_type` 'all' | 'one_time' | 'subscription', required
        - `target_type` 'all' | 'collection', required
        - `target_collections` object[], required
          - `id` union
            - number
            - string
          - `url` string
          - `restriction_text` string
        - `target_products` object[], required
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
          - `sort_key` number, required
        - `session_options` unknown, required
        - `auto_refund_seconds` unknown, required
        - `expiry_options` object, required
          - `kind` 'does_not_expire', required
          - `seconds` unknown, required
        - `redeemable_expiry_options` object, nullable, required
          - `after_duration` object, required
            - `seconds` number, required
        - `supported_channels` string[], required
        - `available_countries` string[], nullable, required
        - `kind` 'cart_discount_voucher', required
        - `recurring_cycle_limit` number, nullable, required
        - `supports_active_subscriptions` boolean
      - object
        - `id` number, required
        - `title` string, required
        - `title_template` string, nullable, required
        - `description` string, nullable, required
        - `sort_key` number, required
        - `content` object, required
        - `point_cost` number, required
        - `method` 'voucher', required
        - `discount_type` 'flat', required
        - `discount_amount` number, required
        - `minimum_spend` unknown, required
        - `usage_limit` 1, required
        - `min_redemption_amount` number, required
        - `max_redemption_amount` number, required
        - `max_free_shipping` unknown, required
        - `site_id` number, required
        - `target_site` object, required
          - `id` number, required
          - `name` string, required
          - `url` string, required
        - `order_type` 'all' | 'one_time', required
        - `target_type` 'all' | 'collection', required
        - `target_collections` object[], required
          - `id` union
            - number
            - string
          - `url` string
          - `restriction_text` string
        - `target_products` object[], required
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
          - `sort_key` number, required
        - `session_options` object, required
          - `kind` 'checkout', required
          - `session_limit` 1, required
        - `auto_refund_seconds` number, required
        - `expiry_options` object, required
          - `kind` 'duration', required
          - `seconds` number, required
        - `redeemable_expiry_options` unknown, required
        - `supported_channels` string[], required
        - `available_countries` string[], nullable, required
        - `kind` 'checkout_redemption', required
        - `redemption_amount_step` number, nullable, required
        - `fixed_redemption_amounts` number[], nullable, required
        - `fixed_redemption_amount_min_spends` object[], nullable, required
          - `amount` number, required
          - `min_spend_before_discount` number, nullable, required
        - `min_spend_after_discount` number, nullable, required
        - `min_spend_before_discount` number, nullable, required
        - `hide_unavailable_discounts` boolean
      - object
        - `id` number, required
        - `title` string, required
        - `title_template` string, nullable, required
        - `description` string, nullable, required
        - `sort_key` number, required
        - `content` object, required
        - `point_cost` number, required
        - `method` 'voucher', required
        - `discount_type` 'flat' | 'percentage', required
        - `discount_amount` number, required
        - `minimum_spend` number, nullable, required
        - `usage_limit` 1, required
        - `min_redemption_amount` 1, required
        - `max_redemption_amount` 1, required
        - `max_free_shipping` unknown, required
        - `site_id` number, required
        - `target_site` object, required
          - `id` number, required
          - `name` string, required
          - `url` string, required
        - `order_type` 'all', required
        - `target_type` 'collection', required
        - `target_collections` object[], required
          - `id` union
            - number
            - string
          - `url` string
          - `restriction_text` string
        - `target_products` object[], required
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
          - `sort_key` number, required
        - `session_options` unknown, required
        - `auto_refund_seconds` unknown, required
        - `expiry_options` object, required
          - `kind` 'does_not_expire', required
          - `seconds` unknown, required
        - `redeemable_expiry_options` object, nullable, required
          - `after_duration` object, required
            - `seconds` number, required
        - `supported_channels` string[], required
        - `available_countries` string[], nullable, required
        - `kind` 'collection_discount_voucher', required
      - object
        - `id` number, required
        - `title` string, required
        - `title_template` string, nullable, required
        - `description` string, nullable, required
        - `sort_key` number, required
        - `content` object, required
          - `fulfilment_instructions` string, nullable, required
          - `featured_image_url` string, nullable
        - `point_cost` number, required
        - `method` 'store_fulfilment' | 'voucher', required
        - `discount_type` 'custom', required
        - `discount_amount` unknown, required
        - `minimum_spend` unknown, required
        - `usage_limit` number, required
        - `min_redemption_amount` number, required
        - `max_redemption_amount` number, required
        - `max_free_shipping` unknown, required
        - `site_id` number, required
        - `target_site` object, required
          - `id` number, required
          - `name` string, required
          - `url` string, required
        - `order_type` 'all', required
        - `target_type` 'custom', required
        - `target_collections` object[], required
          - `id` union
            - number
            - string
          - `url` string
          - `restriction_text` string
        - `target_products` object[], required
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
          - `sort_key` number, required
        - `session_options` unknown, required
        - `auto_refund_seconds` unknown, required
        - `expiry_options` object, required
          - `kind` 'does_not_expire', required
          - `seconds` unknown, required
        - `redeemable_expiry_options` unknown, required
        - `supported_channels` string[], required
        - `available_countries` string[], nullable, required
        - `kind` 'custom', required
      - object
        - `id` number, required
        - `title` string, required
        - `title_template` string, nullable, required
        - `description` string, nullable, required
        - `sort_key` number, required
        - `content` object, required
        - `point_cost` number, required
        - `method` 'voucher', required
        - `discount_type` 'percentage', required
        - `discount_amount` 100, required
        - `minimum_spend` number, nullable, required
        - `usage_limit` 1, required
        - `min_redemption_amount` 1, required
        - `max_redemption_amount` 1, required
        - `max_free_shipping` number, nullable, required
        - `site_id` number, required
        - `target_site` object, required
          - `id` number, required
          - `name` string, required
          - `url` string, required
        - `order_type` 'all', required
        - `target_type` 'shipping', required
        - `target_collections` object[], required
          - `id` union
            - number
            - string
          - `url` string
          - `restriction_text` string
        - `target_products` object[], required
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
          - `sort_key` number, required
        - `session_options` unknown, required
        - `auto_refund_seconds` unknown, required
        - `expiry_options` object, required
          - `kind` 'does_not_expire', required
          - `seconds` unknown, required
        - `redeemable_expiry_options` object, nullable, required
          - `after_duration` object, required
            - `seconds` number, required
        - `supported_channels` string[], required
        - `available_countries` string[], nullable, required
        - `kind` 'free_shipping_voucher', required
      - object
        - `id` number, required
        - `title` string, required
        - `title_template` string, nullable, required
        - `description` string, nullable, required
        - `sort_key` number, required
        - `content` object, required
        - `point_cost` number, required
        - `method` 'gift_card', required
        - `discount_type` 'flat', required
        - `discount_amount` number, required
        - `minimum_spend` unknown, required
        - `usage_limit` 1, required
        - `min_redemption_amount` 1, required
        - `max_redemption_amount` 1, required
        - `max_free_shipping` unknown, required
        - `site_id` number, required
        - `target_site` object, required
          - `id` number, required
          - `name` string, required
          - `url` string, required
        - `order_type` 'all', required
        - `target_type` 'all', required
        - `target_collections` object[], required
          - `id` union
            - number
            - string
          - `url` string
          - `restriction_text` string
        - `target_products` object[], required
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
          - `sort_key` number, required
        - `session_options` unknown, required
        - `auto_refund_seconds` unknown, required
        - `expiry_options` object, required
          - `kind` 'does_not_expire', required
          - `seconds` unknown, required
        - `redeemable_expiry_options` object, nullable, required
          - `after_duration` object, required
            - `seconds` number, required
        - `supported_channels` string[], required
        - `available_countries` string[], nullable, required
        - `kind` 'gift_card', required
      - object
        - `id` number, required
        - `title` string, required
        - `title_template` string, nullable, required
        - `description` string, nullable, required
        - `sort_key` number, required
        - `content` object, required
          - `featured_image_url` string, nullable
        - `point_cost` number, required
        - `method` 'voucher', required
        - `discount_type` 'percentage', required
        - `discount_amount` number, required
        - `minimum_spend` number, nullable, required
        - `usage_limit` 1, required
        - `min_redemption_amount` 1, required
        - `max_redemption_amount` 1, required
        - `max_free_shipping` unknown, required
        - `site_id` number, required
        - `target_site` object, required
          - `id` number, required
          - `name` string, required
          - `url` string, required
        - `order_type` 'all', required
        - `target_type` 'product', required
        - `target_collections` object[], required
          - `id` union
            - number
            - string
          - `url` string
          - `restriction_text` string
        - `target_products` object[], required
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
          - `sort_key` number, required
        - `session_options` unknown, required
        - `auto_refund_seconds` unknown, required
        - `expiry_options` object, required
          - `kind` 'does_not_expire', required
          - `seconds` unknown, required
        - `redeemable_expiry_options` object, nullable, required
          - `after_duration` object, required
            - `seconds` number, required
        - `supported_channels` string[], required
        - `available_countries` string[], nullable, required
        - `kind` 'product_discount_voucher', required
      - object
        - `id` number, required
        - `title` string, required
        - `title_template` string, nullable, required
        - `description` string, nullable, required
        - `sort_key` number, required
        - `content` object, required
        - `point_cost` number, required
        - `method` 'subscription_buy_with_points', required
        - `discount_type` 'percentage', required
        - `discount_amount` number, required
        - `minimum_spend` number, nullable, required
        - `usage_limit` number, required
        - `min_redemption_amount` 1, required
        - `max_redemption_amount` 1, required
        - `max_free_shipping` unknown, required
        - `site_id` number, required
        - `target_site` object, required
          - `id` number, required
          - `name` string, required
          - `url` string, required
        - `order_type` 'subscription', required
        - `target_type` 'product', required
        - `target_collections` object[], required
          - `id` union
            - number
            - string
          - `url` string
          - `restriction_text` string
        - `target_products` object[], required
          - `id` union
            - number
            - string
          - `variant_id` number
          - `sku` string
          - `url` string
          - `image_url` string
          - `title` string
          - `handle` string
          - `inventory_count` number, nullable, required: The current inventory count of this product variant, or `null` if inventory is not tracked. If the count is zero, you should ensure it is not selectable by customers when redeeming the reward
          - `sort_key` number, required
        - `session_options` unknown, required
        - `auto_refund_seconds` number, required
        - `expiry_options` object, required
          - `kind` 'duration', required
          - `seconds` number, required
        - `redeemable_expiry_options` unknown, required
        - `supported_channels` string[], required
        - `available_countries` string[], nullable, required
        - `kind` 'subscription_buy_with_points', required
    - `state` 'approved' | 'declined' | 'expired' | 'pending' | 'void', required
    - `session` object, nullable, required: For session-based rewards, this includes information about the session in which the reward was claimed
      - `kind` 'cart' | 'checkout' | 'custom' | 'draft_order', required
      - `token` string, required
    - `auto_refund_at` string, nullable, required: `ISO 8601` timestamp indicating when this reward will automatically be voided and refunded if it has not yet been used, or `null` if not applicable
    - `expires_at` string, nullable, required: Deprecated in favour of `auto_refund_at`

## Other responses

- `400`: Bad Request
- `401`: 401
- `403`: 403
- `404`: 404

## Changes

- **2026-11-03** `69cbd7bf7128`: 3 breaking, 2 warning, 10 info
  - added `#/components/schemas/RewardRedeemableProductGrant, #/components/schemas/RewardRedeemableTiktokCoupon` to the `claimed_reward/redeemable` response property `oneOf` list for the response status `201`
  - removed 'propertyNames' constraint from the `claimed_reward/reward/oneOf[subschema #2: Product (cart)]/content` response property for the status `201`
  - removed 'propertyNames' constraint from the `claimed_reward/reward/oneOf[subschema #9: Product (voucher)]/content` response property for the status `201`
  - the `multiplier` request property's exclusiveMinimum was set to `0.00`
  - …11 more

[Operation history](https://skmtc.dev/loyaltylion/apis/loyaltylion-admin-api/changes/v2/customers/:merchant_id/claimed_rewards/post.md)

---

[API](https://skmtc.dev/loyaltylion/apis/loyaltylion-admin-api.md) - [All operations](https://skmtc.dev/loyaltylion/apis/loyaltylion-admin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/loyaltylion/apis/loyaltylion-admin-api/revisions/69cbd7bf7128?raw)