Skip to main content
POST
/
headless
/
2025-06
/
{site_id}
/
rewards
/
gift_card
/
redeem
cURL
curl --request POST \
  --url https://api.loyaltylion.com/headless/2025-06/{site_id}/rewards/gift_card/redeem \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reward_id": 123,
  "customer_merchant_id": "<string>"
}'
{
  "gift_card_code": "8c88rfd8t8d6yxp9",
  "claimed_reward": {
    "id": 123,
    "claimed_at": "<string>",
    "reward_id": 123,
    "title": "$5 voucher",
    "state": "approved",
    "source": {
      "kind": "<string>",
      "points_cost": 123
    },
    "auto_refund_at": "<string>",
    "redeemable": {
      "usage_status": "not_used",
      "kind": "<string>",
      "code_last_characters": "<string>",
      "initial_balance": {
        "amount": 9.9,
        "formatted": "$9.90"
      },
      "current_balance": {
        "amount": 9.9,
        "formatted": "$9.90"
      },
      "expires_at": "<string>"
    }
  },
  "customer": {
    "state": "<string>",
    "id": 123,
    "merchant_id": "<string>",
    "email": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "points_approved": 123,
    "points_pending": 123,
    "points_spent": 123,
    "enrolled_at": "<string>",
    "tier_membership": {
      "tier_id": 123,
      "started_at": "2025-01-01T12:00:00Z",
      "expires_at": "2026-01-01T12:00:00Z",
      "progress": {
        "kind": "<string>",
        "valid_until": "<string>",
        "points_needed_for_renewal": 123,
        "upgrade_tier_id": 123,
        "points_needed_for_upgrade": 123,
        "tier_points": {
          "now": 123,
          "at_expiration": 123
        }
      }
    },
    "birthday": {
      "month": 6,
      "day": 25
    },
    "next_birthday": "2025-06-25",
    "claimed_rewards": [
      {
        "id": 123,
        "claimed_at": "<string>",
        "reward_id": 123,
        "title": "$5 voucher",
        "state": "approved",
        "source": {
          "kind": "<string>",
          "points_cost": 123
        },
        "redeemable": {
          "usage_status": "not_used",
          "kind": "<string>",
          "code_last_characters": "<string>",
          "initial_balance": {
            "amount": 9.9,
            "formatted": "$9.90"
          },
          "current_balance": {
            "amount": 9.9,
            "formatted": "$9.90"
          },
          "expires_at": "<string>"
        },
        "auto_refund_at": "<string>"
      }
    ],
    "available_rewards": [
      {
        "id": 123,
        "limit": {
          "count": 123,
          "interval": "day"
        },
        "kind": "<string>",
        "properties": {
          "initial_balance": {
            "amount": 9.9,
            "formatted": "$9.90"
          }
        },
        "variant": {
          "tier_id": 123,
          "title": "$5 voucher",
          "enabled": true,
          "cost": {
            "kind": "<string>",
            "points": 123
          },
          "cost_text": "100 points"
        },
        "context": {
          "can_redeem": {
            "state": "<string>"
          },
          "last_claimed_at": "<string>",
          "claim_count": 123,
          "claim_limit": {
            "state": "<string>"
          }
        }
      }
    ],
    "available_rules": [
      {
        "id": 123,
        "limit": {
          "count": 123,
          "interval": "day"
        },
        "kind": "<string>",
        "variant": {
          "tier_id": 123,
          "title": "Make a purchase",
          "enabled": true,
          "result": {
            "kind": "<string>",
            "per_currency_unit": 1,
            "points": 5
          },
          "result_short_text": "5 points per $1"
        },
        "context": {
          "last_completed_at": "<string>",
          "completion_count": 123,
          "completion_limit": {
            "state": "<string>"
          }
        }
      }
    ],
    "history": [
      {
        "kind": "<string>",
        "label": "Join our program",
        "date": "<string>",
        "points": 1,
        "points_text": "500 points",
        "rule": {
          "id": 123,
          "kind": "birthday"
        },
        "points_will_approve_at": "<string>",
        "points_will_expire_at": "<string>",
        "state": "pending"
      }
    ],
    "active_cart_redemptions": [
      {
        "id": "<string>",
        "claimed_reward_id": 123,
        "expires_at": "<string>",
        "product": {
          "id": "<string>",
          "handle": "<string>",
          "title": "<string>",
          "url": "<string>",
          "image_url": "<string>",
          "variant": {
            "id": "<string>",
            "title": "<string>",
            "inventory_count": 123
          }
        },
        "quantity": 123,
        "cart_id": "<string>",
        "cart_line": {
          "kind": "<string>",
          "merchandise_id": "gid://shopify/ProductVariant/1001",
          "product_id": "gid://shopify/Product/100",
          "quantity": 1,
          "attributes": [
            {
              "key": "__lion_sfp_id",
              "value": "19fdf4cb"
            }
          ]
        },
        "current_cart_state": {
          "in_cart": true,
          "cart_requirements_met": true,
          "cart_requirements_detail": {
            "minimum_cart_total": {
              "state": "<string>"
            },
            "minimum_line_item_quantity": {
              "state": "<string>"
            }
          }
        }
      }
    ],
    "email_marketing_consent": {
      "state": "subscribed"
    },
    "sms_marketing_consent": {
      "state": "subscribed"
    },
    "referral_urls": {
      "direct": "<string>",
      "facebook": "<string>",
      "twitter": "<string>",
      "email": "<string>",
      "whatsapp": "<string>",
      "device_share": "<string>"
    }
  }
}
Use this endpoint to redeem a gift_card reward. If the redemption is successful, the new claimed reward and a unique gift card code will be included in the response. The new gift card code can be seen once only in the in the gift_card_code response field. It’s important that you instruct the customer to copy and save the code.

Authorizations

​
Authorization
string
header
required

An API key linked to a Program in LoyaltyLion, with a set of permissions (scopes). API keys can be created manually, or acquired through an OAuth2 flow. The API key should be provided as a Bearer token in the Authorization header

Path Parameters

​
site_id
number
required

Your LoyaltyLion Site ID

Query Parameters

​
channel
enum<string>

The sales channel from which this request is made. Must be provided as this query parameter, or the X-LoyaltyLion-Channel header

Available options:
web,
pos,
mobile

Body

application/json

Body

​
reward_id
number
required

The LoyaltyLion ID of the reward to redeem

​
customer_merchant_id
string
required

The ID of the customer (in your ecommerce store or platform) to redeem the reward for. For Shopify stores, you can pass either a GID or a regular numeric ID.

This must be a customer whose state is enrolled

Response

201

​
gift_card_code
string
required

The full gift card code. This is the only time the full code can be seen through the API

Example:

"8c88rfd8t8d6yxp9"

​
claimed_reward
object
required

The new claimed reward. The last few characters of the gift card code can be found in claimed_reward.redeemable.code_last_characters

​
customer
object
required

The customer object, updated as of the reward redemption, i.e. their claimed_rewards will include the new redemption. This customer will always have state set to enrolled, as only enrolled customers can redeem rewards