Headless API
Guides
- Shopify Hydrogen
Gift Card
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": "points_redemption",
"points_cost": 123
},
"auto_refund_at": "<string>",
"redeemable": {
"usage_status": "not_used",
"kind": "gift_card",
"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": "enrolled",
"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": "points",
"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": "points_redemption",
"points_cost": 123
},
"redeemable": {
"usage_status": "not_used",
"kind": "gift_card",
"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": "gift_card",
"properties": {
"initial_balance": {
"amount": 9.9,
"formatted": "$9.90"
}
},
"variant": {
"tier_id": 123,
"title": "$5 voucher",
"enabled": true,
"cost": {
"kind": "fixed",
"points": 123
},
"cost_text": "100 points"
},
"context": {
"can_redeem": {
"state": "redeemable"
},
"last_claimed_at": "<string>",
"claim_count": 123,
"claim_limit": {
"state": "no_limit"
}
}
}
],
"available_rules": [
{
"id": 123,
"limit": {
"count": 123,
"interval": "day"
},
"kind": "birthday",
"variant": {
"tier_id": 123,
"title": "Make a purchase",
"enabled": true,
"result": {
"kind": "points",
"per_currency_unit": 1,
"points": 5
},
"result_short_text": "5 points per $1"
},
"context": {
"last_completed_at": "<string>",
"completion_count": 123,
"completion_limit": {
"state": "no_limit"
}
}
}
],
"active_cart_redemptions": [
{
"id": "<string>",
"claimed_reward_id": 123,
"expires_at": "<string>",
"product": {
"id": "<string>",
"title": "<string>",
"url": "<string>",
"image_url": "<string>",
"variant": {
"id": "<string>",
"title": "<string>"
}
},
"quantity": 123,
"cart_id": "<string>",
"cart_line": {
"kind": "shopify",
"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": "no_requirement"
},
"minimum_line_item_quantity": {
"state": "no_requirement"
}
}
}
}
],
"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
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
Your LoyaltyLion Site ID
Query Parameters
The sales channel from which this request is made. Must be provided as this query parameter, or the X-LoyaltyLion-Channel
header
web
, pos
, mobile
Body
Body
The body is of type object
.
Response
201
The response is of type object
.
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": "points_redemption",
"points_cost": 123
},
"auto_refund_at": "<string>",
"redeemable": {
"usage_status": "not_used",
"kind": "gift_card",
"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": "enrolled",
"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": "points",
"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": "points_redemption",
"points_cost": 123
},
"redeemable": {
"usage_status": "not_used",
"kind": "gift_card",
"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": "gift_card",
"properties": {
"initial_balance": {
"amount": 9.9,
"formatted": "$9.90"
}
},
"variant": {
"tier_id": 123,
"title": "$5 voucher",
"enabled": true,
"cost": {
"kind": "fixed",
"points": 123
},
"cost_text": "100 points"
},
"context": {
"can_redeem": {
"state": "redeemable"
},
"last_claimed_at": "<string>",
"claim_count": 123,
"claim_limit": {
"state": "no_limit"
}
}
}
],
"available_rules": [
{
"id": 123,
"limit": {
"count": 123,
"interval": "day"
},
"kind": "birthday",
"variant": {
"tier_id": 123,
"title": "Make a purchase",
"enabled": true,
"result": {
"kind": "points",
"per_currency_unit": 1,
"points": 5
},
"result_short_text": "5 points per $1"
},
"context": {
"last_completed_at": "<string>",
"completion_count": 123,
"completion_limit": {
"state": "no_limit"
}
}
}
],
"active_cart_redemptions": [
{
"id": "<string>",
"claimed_reward_id": 123,
"expires_at": "<string>",
"product": {
"id": "<string>",
"title": "<string>",
"url": "<string>",
"image_url": "<string>",
"variant": {
"id": "<string>",
"title": "<string>"
}
},
"quantity": 123,
"cart_id": "<string>",
"cart_line": {
"kind": "shopify",
"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": "no_requirement"
},
"minimum_line_item_quantity": {
"state": "no_requirement"
}
}
}
}
],
"referral_urls": {
"direct": "<string>",
"facebook": "<string>",
"twitter": "<string>",
"email": "<string>",
"whatsapp": "<string>",
"device_share": "<string>"
}
}
}