POST
/
headless
/
2025-06
/
{site_id}
/
rules
/
instagram_follow
/
complete
cURL
curl --request POST \
  --url https://api.loyaltylion.com/headless/2025-06/{site_id}/rules/instagram_follow/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": "Follow us on Instagram",
      "date": "2025-06-01T15:00:00Z",
      "state": "approved",
      "points": 100,
      "points_text": "100 points",
      "rule": {
        "id": 1,
        "kind": "instagram_follow"
      },
      "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 instagram_follow rule for an enrolled customer. This should be called once a customer has followed, or (more commonly), shown an intention to follow, the Instagram profile specified in the rule’s instagram_handle property. Unless you have a full integration with a custom Instagram app and can ensure the user has followed the profile, our recommended approach is to open the relevant TikTok profile in a new window or in-app browser, and then call this endpoint either immediately, or after a short delay. 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