POST
/
headless
/
2025-06
/
{site_id}
/
customers
/
{merchant_id}
/
email_marketing
/
subscribe
cURL
curl --request POST \
  --url https://api.loyaltylion.com/headless/2025-06/{site_id}/customers/{merchant_id}/email_marketing/subscribe \
  --header 'Authorization: Bearer <token>'
{
  "updated": true,
  "email_marketing_consent": {
    "state": "subscribed"
  },
  "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>"
          }
        },
        "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>"
    }
  },
  "actions": [
    {
      "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"
    }
  ]
}
This endpoint is currently only supported for Shopify stores
Subscribe a customer to email marketing. This will set the customer’s email marketing consent in your Shopify store, so it’s important that you only call this endpoint once the customer has provided explicit consent. The customer’s registered email will be used for the email marketing subscription; it’s not possible to subscribe any other email address. If the customer is already subscribed to email marketing, the updated property will be false. Otherwise, they will be subscribed and the updated property will be true. In case it’s not possible to subscribe the customer, a 422 response will be returned with a code property indicating the reason. If there are relevant rules applicable to the customer, such as a newsletter_signup rule, they will be triggered (unless they have already been completed before), and any related actions will be included in the actions property in the response, such as points or rewards that were awarded.

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

​
merchant_id
string
required

The ID of the customer in your platform or ecommerce store.

For Shopify stores, you can pass either a GID or a regular numeric ID. If you do pass a GID you must encode it as a URL parameter, e.g. gid%3A%2F%2Fshopify%2FCustomer%2F1001

This must be a customer whose state is enrolled

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

Response

200

​
updated
boolean
required

A boolean indicating whether the email marketing consent was updated. If the customer was already subscribed, this will be false

​
email_marketing_consent
object
required

The customer's email marketing consent as of this subscription request. This will always be subscribed, as the request will fail unless we are able to subscribe the customer to email marketing

​
customer
object
required

The customer object, updated as of the email marketing subscription, i.e. their email_marketing_consent will reflect the change. If any rules were triggered as a result of the email marketing subscription, these changes will be reflected too, e.g. new history items, additional points, or new rewards

​
actions
(Earned points from rule · object | Received reward · object)[]
required

A list of actions that were triggered as a result of the email marketing subscription. For example, if there was an applicable "subscribe to newsletter" rule when the customer subscribed, this will include the action that was triggered by the rule