Plug Software
返回 Loyalvia
文档菜单

运营会员计划

API 与 Webhook

让您自己的系统或您使用的其他应用读取和更新会员积分计划:在移动应用中显示余额、为评价发放积分,或在会员升到新等级时做出响应。

注意: API 和 Webhook 包含在 Plus 套餐中。早鸟店铺可免费使用 Pro 的全部功能;Plus 是单独的付费套餐。请参阅套餐与计费。

可以实现什么

  • 显示积分、记录和奖励并可兑换奖励的移动应用或无头商店。
  • 来自其他应用的积分:评价、问答、店铺活动或您自己的后台系统。
  • 将余额和等级同步到邮件、客服或 CRM 工具。

创建 API 密钥

  1. 在应用菜单中打开 API 与 Webhook。
  2. 在创建 API 密钥中,填写能说明用途的名称,例如“移动应用”或其他应用的名称。
  3. 在权限中只勾选需要的项,然后点击创建密钥。
  4. 请立即复制密钥。它只显示一次;如果丢失,请撤销并创建新密钥。
设置作用
读取计划设置、会员、积分记录、奖励和等级。
增加和扣除积分调整会员余额。
兑换奖励用会员的积分兑换奖励并创建折扣码。
管理会员注册顾客并保存生日。
重要: 请妥善保管密钥。只在服务器上使用,切勿放入移动应用或店铺代码中,否则任何人都能复制。密钥一旦泄露,请立即点击旁边的撤销。最多可有 10 个密钥,卸载应用会撤销全部密钥。

添加 Webhook 端点

Webhook 会在事情发生的那一刻通知您的服务器,无需反复查询。

  1. 在 API 与 Webhook 的添加端点中,填写端点 URL:以 https:// 开头的公开地址。
  2. 在事件中选择要发送的内容,然后点击添加端点。
  3. 复制显示的签名密钥。您的服务器用它确认请求来自 Loyalvia。它只显示一次。
  4. 点击发送测试,确认端点能够响应。

每个端点会显示状态是正常还是出错,以及上次发送的时间。连续失败 50 次后会变为已停用;修复服务器后,点击重新启用。最多可有 5 个端点。

Shopify Flow

在 Shopify Flow 工作流中使用 Loyalvia:在计划中发生某事时启动工作流,或在任意工作流中调整积分。它们会显示在 Flow 的 Loyalvia 下,这里无需任何设置。

设置作用
触发器Loyalty member joined, Loyalty points changed, Loyalty tier changed, Loyalty reward redeemed
操作Adjust loyalty points, Enroll customer in loyalty program

例如:客户留下评价时赠送 50 积分、为达到 Gold 的客户添加标签,或将新会员加入 Klaviyo 列表。

开发者参考

调用 API 和接收 Webhook 所需的全部信息。参考内容为英文。

Authentication

Send your API key as a bearer token on every request. The key decides the store, so there's no shop parameter. Requests and responses are JSON.

curl https://api.loyalvia.com/v1/members/7023421390 \
  -H "Authorization: Bearer lv_live_..."

Keys are secret: call the API from your server only, never from a mobile app or browser code. Mobile apps and headless storefronts call your own backend, which calls Loyalvia.

Endpoints

Members are addressed by their numeric Shopify customer id. Texts meant for shoppers (reward names, ways to earn, history lines) follow ?locale=, for example ?locale=fr; the default is English.

Method and pathAccessWhat it does
GET /programreadProgram name, points name, ways to earn, rewards and VIP tiers.
GET /members?email=readFinds a member by email (any letter case).
POST /memberswrite_membersEnrolls a Shopify customer: {"customerId": "7023421390"}. Name and email come from Shopify. Returns 201, or 200 with the existing member.
GET /members/{customerId}readBalance, pending and lifetime points, tier, next tier, referral code, birthday.
GET /members/{customerId}/activityreadPoints history, newest first. ?limit= 1–100 (default 25); pass nextCursor back as ?cursor= for the next page.
GET /members/{customerId}/rewardsreadThe store's rewards, each with redeemable for this member.
GET /members/{customerId}/redemptionsreadThe member's latest 50 reward codes.
POST /members/{customerId}/pointswrite_pointsAdds or removes points: {"points": 50, "reason": "Product review"}. Needs an Idempotency-Key.
POST /members/{customerId}/redeemredeemSpends points on a reward and returns its discount code: {"rewardId": "..."}. Needs an Idempotency-Key.
PUT /members/{customerId}/birthdaywrite_members{"month": 5, "day": 4}. Saved once, as in the widget.

Example: a member

GET https://api.loyalvia.com/v1/members/7023421390

{
  "member": {
    "customerId": "7023421390",
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "balance": 640,
    "pendingPoints": 120,
    "lifetimePoints": 1840,
    "tier": { "id": "6650c1...", "name": "Silver" },
    "nextTier": { "id": "6650c2...", "name": "Gold", "pointsNeeded": 160 },
    "referralCode": "JANE7K2",
    "referralsCount": 3,
    "birthday": { "month": 5, "day": 4 },
    "ordersCount": 9,
    "totalSpent": 412.5,
    "enrolledAt": "2026-03-02T10:14:00.000Z",
    "lastActivityAt": "2026-10-20T08:01:12.000Z"
  }
}

A referral link is your store's address with ?ref= and the code, for example https://your-store.com/?ref=JANE7K2.

Example: add points

curl -X POST https://api.loyalvia.com/v1/members/7023421390/points \
  -H "Authorization: Bearer lv_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: review-88412" \
  -d '{"points": 50, "reason": "Product review"}'

The answer is the member with the new balance. The member gets the same emails as for an adjustment in the app, and the customer's history in the app shows the change as API with your key's name. points is a whole number up to 100,000 either way; removing more than the member's balance is refused.

Idempotency

Adding points and redeeming need an Idempotency-Key header: any unique string up to 255 characters, such as your own review or order id. If a request is retried with the same key within 24 hours, you get the first answer back (with Idempotent-Replayed: true) and nothing happens twice. A key reused for a different request is refused.

Errors

{ "error": { "code": "insufficient_points", "message": "..." } }
StatusCommon codes
400invalid_json, invalid_customer_id, invalid_points, idempotency_key_required
401unauthorized: missing, wrong or revoked key
402plan_required: the store isn't on the Plus plan
403insufficient_scope: the key doesn't have this access
404member_not_found, customer_not_found, reward_unavailable, not_found
409request_in_progress, birthday_already_set
422insufficient_points, tier_required, invalid_date, idempotency_key_reused
429rate_limited, daily_limit
5xxinternal_error, redeem_failed, store_unavailable: safe to retry

Rate limits

10 requests a second per key, with bursts of up to 40, and 50,000 requests a day per store (reset at midnight UTC). Every answer has X-RateLimit-Limit and X-RateLimit-Remaining; a 429 has Retry-After in seconds.

Webhook events

EventSent when
member.enrolledA customer joins the program.
points.changedPoints are earned, spent, removed, expired, or released after the pending period (type: release).
tier.changedA member moves to another VIP tier.
reward.redeemedA member spends points on a reward; includes the discount code.

Members moved in with Import, and tier moves caused by editing your VIP tiers, don't send events. Each request is a POST with a JSON body like this:

{
  "id": "6720f4c1a9e3b2d5c8f01a77",
  "event": "points.changed",
  "createdAt": "2026-10-26T14:03:11.204Z",
  "shop": "your-store.myshopify.com",
  "data": {
    "customerId": "7023421390",
    "activityId": "6720f4c1a9e3b2d5c8f01a70",
    "type": "earn",
    "source": "purchase",
    "points": 120,
    "pending": true,
    "balance": 640,
    "pendingPoints": 120,
    "lifetimePoints": 1840
  }
}

Bodies carry ids and numbers, not names or emails; read those through the API. The headers are X-Loyalvia-Event, X-Loyalvia-Delivery (the same as id, to spot duplicates), X-Loyalvia-Shop and X-Loyalvia-Signature.

Check the signature

X-Loyalvia-Signature looks like t=1793023391,v1=5f2c…: v1 is the hex HMAC-SHA256 of t, a dot and the raw body, keyed with your endpoint's signing secret. Check it against the raw body, before parsing, and refuse old timestamps:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= toleranceSeconds;
  return (
    fresh &&
    expected.length === parts.v1?.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
  );
}

Answers and retries

Answer with any 2xx status within 5 seconds; do slow work after answering. Anything else is retried after 1 minute, 10 minutes, 1 hour and 6 hours. Redirects aren't followed. After 50 failed attempts in a row the endpoint is turned off; fix it, then turn it back on in the app. Events can arrive more than once or out of order, so use id to skip duplicates and createdAt to order them.

没有找到需要的内容,或遇到了问题?联系支持或发送邮件至support@loyalvia.com