Webhook events

Each delivery is a signed POST with the envelope { id, topic, created_at, shop, payload }. Deduplicate on id (stable across retries). How to subscribe and verify signatures: Webhooks.

points.earned

A customer earned points (orders, rules, API awards).

Payload field	Type	Description
customer_id	string	Shopify customer GID, e.g. gid://shopify/Customer/123. Accepted by every endpoint that takes a customer id, as is the numeric legacy_id.
customer_legacy_id	integer or null	The numeric Shopify customer id (the part after the last slash of the GID). (nullable)
points	number
balance_after	number
source	string	What earned them: order, a rule type, api, activity, …

{
  "id": "evt_kFb2p9qArM3w",
  "topic": "points.earned",
  "created_at": "2026-10-01T09:30:00.000Z",
  "shop": "your-store.myshopify.com",
  "payload": {
    "customer_id": "gid://shopify/Customer/7712345",
    "customer_legacy_id": 7712345,
    "points": 120,
    "balance_after": 120,
    "source": "order"
  }
}

points.adjusted

A balance was corrected or deducted.

Payload field	Type	Description
customer_id	string	Shopify customer GID, e.g. gid://shopify/Customer/123. Accepted by every endpoint that takes a customer id, as is the numeric legacy_id.
customer_legacy_id	integer or null	The numeric Shopify customer id (the part after the last slash of the GID). (nullable)
points	number	Signed: negative for deductions.
balance_after	number
reason	string
source	string

{
  "id": "evt_kFb2p9qArM3w",
  "topic": "points.adjusted",
  "created_at": "2026-10-01T09:30:00.000Z",
  "shop": "your-store.myshopify.com",
  "payload": {
    "customer_id": "gid://shopify/Customer/7712345",
    "customer_legacy_id": 7712345,
    "points": 120,
    "balance_after": 120,
    "reason": "Goodwill after a late delivery",
    "source": "order"
  }
}

reward.redeemed

Points were spent on a reward.

Payload field	Type	Description
customer_id	string	Shopify customer GID, e.g. gid://shopify/Customer/123. Accepted by every endpoint that takes a customer id, as is the numeric legacy_id.
customer_legacy_id	integer or null	The numeric Shopify customer id (the part after the last slash of the GID). (nullable)
points_spent	number
balance_after	number
reward_name	string
discount_code	string

{
  "id": "evt_kFb2p9qArM3w",
  "topic": "reward.redeemed",
  "created_at": "2026-10-01T09:30:00.000Z",
  "shop": "your-store.myshopify.com",
  "payload": {
    "customer_id": "gid://shopify/Customer/7712345",
    "customer_legacy_id": 7712345,
    "points_spent": 120,
    "balance_after": 120,
    "reward_name": "10% off",
    "discount_code": "CHARM-7Q2X9"
  }
}

tier.changed

A customer reached a new VIP tier.

Payload field	Type	Description
customer_id	string	Shopify customer GID, e.g. gid://shopify/Customer/123. Accepted by every endpoint that takes a customer id, as is the numeric legacy_id.
customer_legacy_id	integer or null	The numeric Shopify customer id (the part after the last slash of the GID). (nullable)
tier_name	string
tier_id	string
tier_handle	string
previous_tier_id	string
previous_tier_handle	string

{
  "id": "evt_kFb2p9qArM3w",
  "topic": "tier.changed",
  "created_at": "2026-10-01T09:30:00.000Z",
  "shop": "your-store.myshopify.com",
  "payload": {
    "customer_id": "gid://shopify/Customer/7712345",
    "customer_legacy_id": 7712345,
    "tier_name": "Gold",
    "tier_id": "gold",
    "tier_handle": "gold",
    "previous_tier_id": "silver",
    "previous_tier_handle": "silver"
  }
}

tier.approaching

A customer got close to the next tier.

Payload field	Type	Description
customer_id	string	Shopify customer GID, e.g. gid://shopify/Customer/123. Accepted by every endpoint that takes a customer id, as is the numeric legacy_id.
customer_legacy_id	integer or null	The numeric Shopify customer id (the part after the last slash of the GID). (nullable)
next_tier_name	string
next_tier_id	string
next_tier_handle	string
gap_text	string	Human-readable gap, e.g. 120 points.
current_tier_id	string

{
  "id": "evt_kFb2p9qArM3w",
  "topic": "tier.approaching",
  "created_at": "2026-10-01T09:30:00.000Z",
  "shop": "your-store.myshopify.com",
  "payload": {
    "customer_id": "gid://shopify/Customer/7712345",
    "customer_legacy_id": 7712345,
    "next_tier_name": "Platinum",
    "next_tier_id": "platinum",
    "next_tier_handle": "platinum",
    "gap_text": "120 points",
    "current_tier_id": "gold"
  }
}

store_credit.issued

Store credit landed on a customer’s account.

Payload field	Type	Description
customer_id	string	Shopify customer GID, e.g. gid://shopify/Customer/123. Accepted by every endpoint that takes a customer id, as is the numeric legacy_id.
customer_legacy_id	integer or null	The numeric Shopify customer id (the part after the last slash of the GID). (nullable)
amount	number
currency_code	string
reason	string

{
  "id": "evt_kFb2p9qArM3w",
  "topic": "store_credit.issued",
  "created_at": "2026-10-01T09:30:00.000Z",
  "shop": "your-store.myshopify.com",
  "payload": {
    "customer_id": "gid://shopify/Customer/7712345",
    "customer_legacy_id": 7712345,
    "amount": 1,
    "currency_code": "EUR",
    "reason": "Goodwill after a late delivery"
  }
}

referral.completed

A referred friend’s qualifying order completed. customer_id is the referred customer.

Payload field	Type	Description
customer_id	string	Shopify customer GID, e.g. gid://shopify/Customer/123. Accepted by every endpoint that takes a customer id, as is the numeric legacy_id.
customer_legacy_id	integer or null	The numeric Shopify customer id (the part after the last slash of the GID). (nullable)
order_id	integer or string	The referred friend’s order.
referrer_email	string
order_amount	number
gift_delivery	string

{
  "id": "evt_kFb2p9qArM3w",
  "topic": "referral.completed",
  "created_at": "2026-10-01T09:30:00.000Z",
  "shop": "your-store.myshopify.com",
  "payload": {
    "customer_id": "gid://shopify/Customer/7712345",
    "customer_legacy_id": 7712345,
    "order_id": 1,
    "referrer_email": "friend@example.com",
    "order_amount": 1,
    "gift_delivery": "discount_code"
  }
}