POST
/
headless
/
2025-06
/
{site_id}
/
rewards
/
free_shipping_voucher
/
redeem
curl --request POST \
  --url https://api.loyaltylion.com/headless/2025-06/{site_id}/rewards/free_shipping_voucher/redeem \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reward_id": 123,
  "customer_merchant_id": "<string>"
}'
{
  "voucher_code": "LL-XYA3816",
  "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": "free_shipping_voucher",
      "code": "<string>",
      "max_shipping": {
        "amount": 9.9,
        "formatted": "$9.90"
      },
      "expires_at": "<string>",
      "used_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 free_shipping_voucher reward, which will apply free shipping to the cart. If the redemption is successful, the new claimed reward and a unique voucher (coupon) code will be included in the response.

You can show the voucher code to the customer and instruct them to apply it to their cart later. Or, if supported by your ecommerce platform, you can apply the voucher code to the cart directly, which provides a superior user experience.

Note that free shipping vouchers may have a max shipping amount, which will be in in claimed_reward.redeemable.max_shipping. If present, this should be communicated to the customer to avoid confusion.

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

The body is of type object.

Response

201
application/json

201

The response is of type object.