Skip to main content
POST
/
headless
/
2025-06
/
{site_id}
/
rewards
/
active_subscription_product
/
redeem
cURL
curl --request POST \
  --url https://api.loyaltylion.com/headless/2025-06/{site_id}/rewards/active_subscription_product/redeem \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reward_id": 123,
  "customer_merchant_id": "<string>",
  "variant_id": "<string>",
  "shipping_address": {
    "kind": "<string>",
    "id": 123
  }
}
'
{
  "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>",
      "product": {
        "id": "<string>",
        "handle": "<string>",
        "title": "<string>",
        "url": "<string>",
        "image_url": "<string>",
        "variant": {
          "id": "<string>",
          "title": "<string>",
          "inventory_count": 123
        }
      },
      "quantity": 123,
      "subscription_details": {
        "kind": "<string>",
        "address_id": 123,
        "onetime_id": 123,
        "next_subscription_scheduled_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
        },
        "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>"
        }
      }
    ],
    "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>"
    }
  }
}
The ReCharge integration must have been configured in LoyaltyLion before using this reward.
Use this endpoint to redeem an active subscription product reward, which will automatically add a free product to a customer’s upcoming subscription order. If the customer does not currently have any active subscriptions, the redemption will fail with an error.code of no_active_subscriptions

​
Choosing a variant

The reward may have been configured with multiple eligible product variants. If this is the case, you’ll need to let the customer choose which variant they want to redeem, and then pass that ID as variant_id when performing the redemption.

​
Choosing a subscription address

By default, the product will be included with the customer’s next upcoming subscription order. Alternatively, you can ask the customer to select which address they want the free product to be sent to. You can use the ReCharge API to fetch a list of the customer’s active addresses and ask them to choose which one the free product should be sent to.

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

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

​
variant_id
string
required

The product variant ID to redeem. If the product reward includes multiple variants, you should ask the customer which one they want to redeem

​
shipping_address
object

If you are using ReCharge for subscriptions, you can optionally pass a shipping address ID which will be used as the shipping address for the free product. You can fetch shipping addresses using the ReCharge API. If not provided, the free product will included with the customer's next recurring subscription order

Response

201

​
claimed_reward
object
required

The new claimed reward. Details about the product can be found in claimed_reward.redeemable.product, and details about the subscription can be found in claimed_reward.redeemable.subscription_details

​
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