Plug Software
กลับไปที่ Loyalvia
เมนูเอกสารประกอบ

ดำเนินโปรแกรม

API และเว็บฮุก

ให้ระบบของคุณเองหรือแอปอื่นที่ใช้อยู่ อ่านและอัปเดตโปรแกรมสะสมคะแนนได้: แสดงยอดในแอปมือถือ ให้คะแนนสำหรับรีวิว หรือดำเนินการเมื่อสมาชิกถึงระดับใหม่

หมายเหตุ: API และเว็บฮุกมีในแพ็กเกจ Plus ร้านค้า early bird ได้ทุกฟีเจอร์ของ Pro ฟรี ส่วน Plus เป็นแพ็กเกจแบบชำระเงินแยกต่างหาก ดู แพ็กเกจและการเรียกเก็บเงิน

สิ่งที่คุณสร้างได้

  • แอปมือถือหรือร้านค้า headless ที่แสดงคะแนน ประวัติ และรางวัล พร้อมให้แลกได้
  • คะแนนจากแอปอื่น: รีวิว แบบทดสอบ กิจกรรมหน้าร้าน หรือระบบหลังบ้านของคุณเอง
  • การซิงค์ยอดและระดับไปยังเครื่องมืออีเมล บริการลูกค้า หรือ CRM

สร้างคีย์ API

  1. ไปที่ API และเว็บฮุก ในเมนูแอป
  2. ในส่วน สร้างคีย์ API ใส่ที่ที่จะใช้คีย์ใน ชื่อ เช่น “แอปมือถือ” หรือชื่อของแอปอื่น
  3. ใน สิทธิ์การเข้าถึง ให้เลือกเฉพาะที่จำเป็น แล้วคลิก สร้างคีย์
  4. คัดลอกคีย์ทันที คีย์จะแสดงเพียงครั้งเดียว หากทำหาย ให้เพิกถอนแล้วสร้างใหม่
การตั้งค่าหน้าที่
อ่านการตั้งค่าโปรแกรม สมาชิก ประวัติคะแนน รางวัล และระดับ
เพิ่มและหักคะแนนปรับยอดของสมาชิก
แลกรางวัลใช้คะแนนของสมาชิกแลกรางวัลและสร้างรหัสส่วนลด
จัดการสมาชิกลงทะเบียนลูกค้าและบันทึกวันเกิด
สำคัญ: เก็บคีย์เป็นความลับ ใช้จากเซิร์ฟเวอร์เท่านั้น ห้ามใส่ในแอปมือถือหรือโค้ดของร้านค้าที่ใครก็คัดลอกได้ หากคีย์รั่วไหล ให้คลิก เพิกถอน ข้างคีย์นั้นทันที คุณมีคีย์ได้สูงสุด 10 คีย์ และการถอนการติดตั้งแอปจะเพิกถอนคีย์ทั้งหมด

เพิ่มปลายทางเว็บฮุก

เว็บฮุกแจ้งเซิร์ฟเวอร์ของคุณทันทีที่มีเหตุการณ์เกิดขึ้น คุณจึงไม่ต้องคอยสอบถามตลอดเวลา

  1. ในหน้า API และเว็บฮุก ส่วน เพิ่มปลายทาง ให้ใส่ URL ปลายทาง: ที่อยู่สาธารณะที่ขึ้นต้นด้วย https://
  2. ใน เหตุการณ์ ให้เลือกสิ่งที่จะส่ง แล้วคลิก เพิ่มปลายทาง
  3. คัดลอกข้อมูลลับสำหรับลงนามที่แสดง เซิร์ฟเวอร์ของคุณใช้ข้อมูลนี้ตรวจสอบว่าคำขอมาจาก Loyalvia ข้อมูลนี้จะแสดงเพียงครั้งเดียว
  4. คลิก ส่งทดสอบ เพื่อตรวจสอบว่าปลายทางตอบกลับ

แต่ละปลายทางแสดงว่า ใช้งาน หรือ ล้มเหลว และส่งล่าสุดเมื่อไร หากล้มเหลวติดต่อกัน 50 ครั้ง ปลายทางจะถูก ปิดใช้งาน ให้แก้ไขเซิร์ฟเวอร์แล้วคลิก เปิดใช้อีกครั้ง คุณมีปลายทางได้สูงสุด 5 รายการ

Shopify Flow

ใช้ Loyalvia ในเวิร์กโฟลว์ของ Shopify Flow: เริ่มเวิร์กโฟลว์เมื่อมีบางอย่างเกิดขึ้นในโปรแกรม หรือเปลี่ยนคะแนนจากเวิร์กโฟลว์ใดก็ได้ จะแสดงใน 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 และรับเว็บฮุก

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