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