POST
/
headless
/
2025-06
/
{site_id}
/
rules
/
custom
/
complete
cURL
curl --request POST \
  --url https://api.loyaltylion.com/headless/2025-06/{site_id}/rules/custom/complete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "rule_id": 123,
  "customer_merchant_id": "<string>"
}'
{
  "actions": [
    {
      "kind": "earned_points_from_rule",
      "label": "Enter our competition",
      "date": "2025-06-01T15:00:00Z",
      "state": "approved",
      "points": 100,
      "points_text": "100 points",
      "rule": {
        "id": 1,
        "kind": "custom"
      },
      "points_will_approve_at": null,
      "points_will_expire_at": null
    }
  ],
  "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": {
          "can_redeem": {
            "state": "redeemable"
          },
          "last_claimed_at": "2025-06-03T00:00:00Z",
          "claim_count": 1,
          "claim_limit": {
            "state": "no_limit"
          }
        }
      },
      {
        "id": 2,
        "kind": "cart_discount_voucher",
        "limit": null,
        "properties": {
          "discount_type": "percentage",
          "discount": {
            "percentage": 10,
            "formatted": "10%"
          },
          "applies_to_order_type": "one_time",
          "recurring_cycle_limit": 1,
          "minimum_spend": {
            "amount": 50,
            "formatted": "$50"
          }
        },
        "variant": {
          "tier_id": 1,
          "enabled": true,
          "title": "10% discount",
          "cost": {
            "kind": "fixed",
            "points": 1000
          },
          "cost_text": "1,000 points"
        },
        "context": {
          "can_redeem": {
            "state": "insufficient_points",
            "additional_points_required": 500
          },
          "last_claimed_at": null,
          "claim_count": 0,
          "claim_limit": {
            "state": "no_limit"
          }
        }
      }
    ],
    "history": [
      {
        "kind": "redeemed_points_for_reward",
        "label": "$5 discount",
        "date": "2025-06-03T15:00:00Z",
        "points": -500,
        "points_text": "-500 points",
        "reward": {
          "id": 1,
          "kind": "cart_discount_voucher"
        },
        "claimed_reward_id": 1,
        "state": "approved"
      },
      {
        "kind": "entered_tier",
        "label": "Entered Silver tier",
        "date": "2025-06-02T15:00:00Z",
        "tier": {
          "id": 1,
          "name": "Silver"
        }
      },
      {
        "kind": "earned_points_from_rule",
        "label": "Joined program",
        "date": "2025-06-01T15:00:00Z",
        "points": 500,
        "points_text": "500 points",
        "points_will_approve_at": null,
        "points_will_expire_at": "2026-06-01T00:00:00Z",
        "state": "approved",
        "rule": {
          "id": 1,
          "kind": "join_program"
        }
      }
    ],
    "active_cart_redemptions": [],
    "email_marketing_consent": {
      "state": "subscribed"
    },
    "sms_marketing_consent": {
      "state": "not_subscribed"
    },
    "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/_"
    }
  }
}
Use this endpoint to complete a specific custom rule for an enrolled customer. This can be called once a customer has completed the relevant activity on your store to award them with points or a reward based on the custom rule’s configured settings. For example, if you have a custom rule for encourage providing feedback on your store, you could call this endpoint once the customer has provided feedback. If the customer is able to complete the rule, a success response will be returned. This response will include a list of actions which will indicate any points or rewards that were awarded based on the rule’s configuration. If the customer is not able to complete the rule, a 422 response will be returned instead. For example, if the customer has already completed the rule an allowed number of times, or the rule isn’t enabled for the customer.

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

​
rule_id
number
required

The LoyaltyLion ID of the rule to complete

​
customer_merchant_id
string
required

The ID of the customer (in your ecommerce store or platform) to complete the rule for. For Shopify stores, you can pass either a GID or a regular numeric ID.

This must be a customer whose state is enrolled

Response

200

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

A list of actions that resulted from the rule's completion, such as points or rewards being awarded

​
customer
object
required

The customer object, updated as of the rule action, i.e. their history, points, and rewards will include any new actions as a result of completing the rule. This customer will always have state set to enrolled, as only enrolled customers can complete rules