POST
/
headless
/
2025-06
/
{site_id}
/
customers
/
{merchant_id}
/
sessions
curl --request POST \
  --url https://api.loyaltylion.com/headless/2025-06/{site_id}/customers/{merchant_id}/sessions \
  --header 'Content-Type: application/json' \
  --data '{
  "customer": {
    "email": "alice@example.com"
  },
  "session": {
    "page_url": "https://store.example.com/products/100"
  }
}'
{
  "channel": "web",
  "currency": "usd",
  "language": "en",
  "customer": {
    "state": "enrolled",
    "id": 1,
    "merchant_id": "1001",
    "email": "alice@example.com",
    "first_name": "Alice",
    "last_name": "Kyako",
    "points_approved": 500,
    "points_pending": 200,
    "points_spent": 500,
    "enrolled_at": "2025-06-01T15:00:00Z",
    "tier_membership": {
      "tier_id": 1,
      "started_at": "2025-06-01T15:00:00Z",
      "expires_at": "2026-06-01T15:00:00Z",
      "progress": {
        "kind": "spend",
        "tier_spend": {
          "now": {
            "amount": 200,
            "formatted": "$200"
          },
          "at_expiration": {
            "amount": 100,
            "formatted": "$100"
          }
        },
        "valid_until": "2026-06-01T15:00:00Z",
        "upgrade_tier_id": 2,
        "spend_needed_for_renewal": null,
        "spend_needed_for_upgrade": {
          "amount": 800,
          "formatted": "$800"
        }
      }
    },
    "birthday": {
      "day": 22,
      "month": 6
    },
    "next_birthday": "2026-06-22",
    "claimed_rewards": [
      {
        "id": 1,
        "claimed_at": "2025-06-03T00:00:00Z",
        "auto_refund_at": null,
        "reward_id": 1,
        "title": "$5 discount",
        "state": "approved",
        "source": {
          "kind": "points_redemption",
          "points_cost": 500
        },
        "redeemable": {
          "kind": "cart_discount_voucher",
          "applies_to_order_type": "all",
          "recurring_cycle_limit": 1,
          "code": "LL-XAIA8471",
          "discount_type": "fixed",
          "discount": {
            "amount": 5,
            "formatted": "$5"
          },
          "minimum_spend": {
            "amount": 50,
            "formatted": "$50"
          },
          "expires_at": "2026-06-03T00:00:00Z",
          "used_at": null,
          "usage_status": "not_used"
        }
      }
    ],
    "available_rules": [
      {
        "id": 1,
        "kind": "pageview",
        "limit": {
          "count": 5,
          "interval": "day"
        },
        "variant": {
          "tier_id": 1,
          "enabled": true,
          "title": "Visit our online store",
          "result": {
            "kind": "points",
            "per_currency_unit": null,
            "points": 10
          },
          "result_short_text": "10 points"
        },
        "context": {
          "last_completed_at": "2025-06-10T05:08:37.582Z",
          "completion_count": 22,
          "completion_limit": {
            "state": "limit_not_reached",
            "interval": "day",
            "allowed_completions_within_interval": 5,
            "completion_count_within_interval": 3,
            "remaining_completions_within_interval": 2
          }
        }
      },
      {
        "id": 2,
        "kind": "join_program",
        "limit": {
          "count": 1,
          "interval": null
        },
        "variant": {
          "tier_id": 1,
          "enabled": true,
          "title": "Join our loyalty program",
          "result": {
            "kind": "points",
            "per_currency_unit": null,
            "points": 100
          },
          "result_short_text": "100 points"
        },
        "context": {
          "last_completed_at": "2025-06-10T07:44:24.537Z",
          "completion_count": 1,
          "completion_limit": {
            "state": "limit_reached_forever"
          }
        }
      },
      {
        "id": 3,
        "kind": "purchase",
        "limit": null,
        "variant": {
          "tier_id": 1,
          "enabled": true,
          "title": "Make a purchase",
          "result": {
            "kind": "points",
            "per_currency_unit": 1,
            "points": 5
          },
          "result_short_text": "5 points per $1"
        },
        "context": {
          "last_completed_at": "2025-06-10T05:08:37.582Z",
          "completion_count": 3,
          "completion_limit": {
            "state": "no_limit"
          }
        }
      }
    ],
    "available_rewards": [
      {
        "id": 1,
        "kind": "cart_discount_voucher",
        "limit": null,
        "properties": {
          "discount_type": "fixed",
          "discount": {
            "amount": 5,
            "formatted": "$5"
          },
          "applies_to_order_type": "one_time",
          "recurring_cycle_limit": 1,
          "minimum_spend": {
            "amount": 10,
            "formatted": "$10"
          }
        },
        "variant": {
          "tier_id": 1,
          "enabled": true,
          "title": "$5 discount",
          "cost": {
            "kind": "fixed",
            "points": 500
          },
          "cost_text": "500 points"
        },
        "context": {
          "last_claimed_at": "2025-06-03T00:00:00Z",
          "claim_count": 1,
          "claim_limit": {
            "state": "no_limit"
          }
        }
      }
    ],
    "referral_urls": {
      "email": "https://prz.io/_",
      "direct": "https://prz.io/_",
      "facebook": "https://prz.io/_",
      "twitter": "https://prz.io/_",
      "whatsapp": "https://prz.io/_",
      "device_share": "https://prz.io/_"
    }
  },
  "configuration": {
    "channel": "web",
    "currency": "usd",
    "language": "en",
    "program": {
      "name": "Lion Rewards"
    },
    "tier_configuration": {
      "boundary_mode": "spend",
      "tiers": [
        {
          "id": 1,
          "name": "Silver",
          "benefit_ids": [
            1
          ],
          "hidden": false,
          "kind": "spend",
          "position": 1,
          "lower_bound": {
            "amount": 0,
            "formatted": "$0"
          },
          "upper_bound": {
            "amount": 99.99,
            "formatted": "$99.99"
          }
        },
        {
          "id": 2,
          "name": "Gold",
          "benefit_ids": [
            1,
            2
          ],
          "hidden": false,
          "kind": "spend",
          "position": 2,
          "lower_bound": {
            "amount": 100,
            "formatted": "$100"
          },
          "upper_bound": null
        }
      ],
      "tier_benefits": [
        {
          "id": 1,
          "label": "Early access to new products",
          "secret": false,
          "details": null
        },
        {
          "id": 2,
          "label": "Free makeup classes",
          "secret": false,
          "details": {
            "plaintext": "Email classes@example.com to sign up to a class\n",
            "html": "<p>Email classes@example.com to sign up to a class</p>"
          }
        }
      ],
      "membership": {
        "mode": "rolling",
        "duration_months": 12
      }
    },
    "referee_incentive": {
      "minimum_spend": {
        "amount": 100,
        "formatted": "$100"
      },
      "incentive_text": "Get a 10% discount on your order with this code when you spend over $100",
      "kind": "cart_discount_voucher",
      "discount_kind": "percentage",
      "discount": {
        "percentage": 10,
        "formatted": "10%"
      }
    },
    "rules": [
      {
        "id": 1,
        "kind": "purchase",
        "variants": [
          {
            "tier_id": 1,
            "enabled": true,
            "title": "Make a purchase",
            "result": {
              "kind": "points",
              "per_currency_unit": 1,
              "points": 5
            },
            "result_short_text": "5 points per $1"
          },
          {
            "tier_id": 2,
            "enabled": true,
            "title": "Make a purchase",
            "result": {
              "kind": "points",
              "per_currency_unit": 1,
              "points": 10
            },
            "result_short_text": "10 points per $1"
          }
        ],
        "limit": null
      },
      {
        "id": 2,
        "kind": "pageview",
        "variants": [
          {
            "tier_id": 1,
            "enabled": true,
            "title": "Visit our online store",
            "result": {
              "kind": "points",
              "per_currency_unit": null,
              "points": 100
            },
            "result_short_text": "100 points"
          },
          {
            "tier_id": 2,
            "enabled": true,
            "title": "Visit our online store",
            "result": {
              "kind": "points",
              "per_currency_unit": null,
              "points": 200
            },
            "result_short_text": "200 points"
          }
        ],
        "limit": {
          "count": 1,
          "interval": "week"
        }
      }
    ],
    "rewards": [
      {
        "id": 1,
        "kind": "cart_discount_voucher",
        "properties": {
          "discount_type": "fixed",
          "discount": {
            "amount": 5,
            "formatted": "$5"
          },
          "applies_to_order_type": "one_time",
          "recurring_cycle_limit": 1,
          "minimum_spend": {
            "amount": 10,
            "formatted": "$10"
          }
        },
        "variants": [
          {
            "tier_id": 1,
            "enabled": true,
            "title": "$5 discount",
            "cost": {
              "kind": "fixed",
              "points": 500
            },
            "cost_text": "500 points"
          },
          {
            "tier_id": 2,
            "enabled": true,
            "title": "$5 discount",
            "cost": {
              "kind": "fixed",
              "points": 400
            },
            "cost_text": "400 points"
          }
        ],
        "limit": null
      },
      {
        "id": 2,
        "kind": "cart_variable_discount_voucher",
        "properties": {
          "minimum_discount": {
            "amount": 1,
            "formatted": "$1"
          },
          "maximum_discount": {
            "amount": 100,
            "formatted": "$100"
          },
          "applies_to_order_type": "all",
          "minimum_spend_before_discount": null,
          "minimum_spend_after_discount": null
        },
        "variants": [
          {
            "tier_id": 1,
            "enabled": false,
            "title": "Redeem points at checkout",
            "cost": {
              "kind": "variable",
              "unit": "discount_amount",
              "points_per_unit": 100
            },
            "cost_text": "100 points per $1"
          },
          {
            "tier_id": 2,
            "enabled": true,
            "title": "Redeem points at checkout",
            "cost": {
              "kind": "variable",
              "unit": "discount_amount",
              "points_per_unit": 100
            },
            "cost_text": "100 points per $1"
          }
        ],
        "limit": null
      }
    ]
  }
}

Initialize a headless session for the customer with the given merchant_id (the ID of the customer in your store or platform).

For convenience, the full program configuration, as returned by the Get Configuration endpoint, is also included in the response.

If you’re building your own headless web UI, you should generally call this once on each page load, or, for a mobile app, once per “session”, e.g. when the customer opens or resumes the app.

Compared to the read-only Get Customer endpoint, this endpoint can create and enroll customers, and will trigger any relevant rules.

  • if no matching customer exists in LoyaltyLion for the given merchant_id, a new customer will be created, potentially enrolled into the program, and returned
  • if a matching customer is found in LoyaltyLion, they may be enrolled and returned

Customers will be enrolled based on the program’s configuration. For example, if the program is configured to auto-enroll customers, they’ll become enrolled automatically when their session is initialized.

For both new and existing customers, program rules may be triggered for the customer. For example:

  • “join program” rule if the customer was just enrolled from this session
  • “pageview” rule if the channel is web and they’re viewing a relevant page
  • “download mobile app” rule if the channel is mobile

Path Parameters

​
site_id
number
required

Your LoyaltyLion Site ID. If a new customer is created from this API call, they'll be created in this Site, which is relevant for multi-site programs

​
merchant_id
string
required

The ID of the customer in your platform or ecommerce store

Minimum length: 1

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

200
application/json

200

The response is of type object.