اپنا پروگرام چلائیں
API اور ویب ہُکس
اپنے سسٹمز، یا آپ کی استعمال کردہ دوسری ایپس کو اپنا لائلٹی پروگرام پڑھنے اور اپ ڈیٹ کرنے دیں: موبائل ایپ میں بیلنس دکھائیں، ریویو پر پوائنٹس دیں، یا ممبر کے نئے درجے تک پہنچنے پر کوئی کارروائی کریں۔
آپ کیا بنا سکتے ہیں
- موبائل ایپ یا ہیڈلیس اسٹور فرنٹ جو پوائنٹس، تاریخچہ اور انعامات دکھائے اور انہیں ریڈیم کرے۔
- دوسری ایپس سے پوائنٹس: ریویوز، کوئز، آپ کے اسٹور کے ایونٹس، یا آپ کا اپنا بیک آفس۔
- بیلنس اور درجوں کو ای میل، ہیلپ ڈیسک یا CRM ٹول میں سنک کرنا۔
API کی بنائیں
- ایپ مینو میں API اور ویب ہُکس پر جائیں۔
- API کی بنائیں کے تحت نام میں لکھیں کہ یہ کہاں استعمال ہوگی، جیسے “موبائل ایپ” یا دوسری ایپ کا نام۔
- رسائی کے تحت صرف وہی منتخب کریں جو ضروری ہے، پھر کی بنائیں پر کلک کریں۔
- کی فوراً کاپی کریں۔ یہ صرف ایک بار دکھائی جاتی ہے؛ اگر کھو جائے تو اسے منسوخ کر کے نئی بنائیں۔
| سیٹنگ | یہ کیا کرتی ہے |
|---|---|
| پڑھنا | پروگرام کی سیٹنگز، ممبرز، پوائنٹس کا تاریخچہ، انعامات اور درجے۔ |
| پوائنٹس شامل اور کم کرنا | ممبرز کے بیلنس ایڈجسٹ کرنا۔ |
| انعامات ریڈیم کرنا | ممبر کے پوائنٹس کسی انعام پر خرچ کرنا اور اس کا ڈسکاؤنٹ کوڈ بنانا۔ |
| ممبرز کا انتظام | کسٹمرز کو شامل کرنا اور سالگرہ محفوظ کرنا۔ |
ویب ہُک اینڈ پوائنٹ شامل کریں
ویب ہُکس کچھ ہوتے ہی آپ کے سرور کو بتا دیتے ہیں، اس لیے آپ کو بار بار پوچھنا نہیں پڑتا۔
- API اور ویب ہُکس پر اینڈ پوائنٹ شامل کریں کے تحت اینڈ پوائنٹ URL درج کریں:
https://سے شروع ہونے والا پبلک پتہ۔ - ایونٹس کے تحت چنیں کہ کیا بھیجنا ہے، پھر اینڈ پوائنٹ شامل کریں پر کلک کریں۔
- ظاہر ہونے والا سائننگ سیکرٹ کاپی کریں۔ آپ کا سرور اس سے چیک کرتا ہے کہ درخواستیں Loyalvia سے آئی ہیں۔ یہ صرف ایک بار دکھایا جاتا ہے۔
- یہ چیک کرنے کے لیے کہ آپ کا اینڈ پوائنٹ جواب دیتا ہے، ٹیسٹ بھیجیں پر کلک کریں۔
ہر اینڈ پوائنٹ دکھاتا ہے کہ وہ فعال ہے یا ناکام ہو رہا ہے، اور آخری بار کب بھیجا گیا۔ مسلسل 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 کال کرنے اور ویب ہُکس وصول کرنے کے لیے ڈیولپر کو جو کچھ چاہیے۔
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 path | Access | What it does |
|---|---|---|
| GET /program | read | Program name, points name, ways to earn, rewards and VIP tiers. |
| GET /members?email= | read | Finds a member by email (any letter case). |
| POST /members | write_members | Enrolls a Shopify customer: {"customerId": "7023421390"}. Name and email come from Shopify. Returns 201, or 200 with the existing member. |
| GET /members/{customerId} | read | Balance, pending and lifetime points, tier, next tier, referral code, birthday. |
| GET /members/{customerId}/activity | read | Points history, newest first. ?limit= 1–100 (default 25); pass nextCursor back as ?cursor= for the next page. |
| GET /members/{customerId}/rewards | read | The store's rewards, each with redeemable for this member. |
| GET /members/{customerId}/redemptions | read | The member's latest 50 reward codes. |
| POST /members/{customerId}/points | write_points | Adds or removes points: {"points": 50, "reason": "Product review"}. Needs an Idempotency-Key. |
| POST /members/{customerId}/redeem | redeem | Spends points on a reward and returns its discount code: {"rewardId": "..."}. Needs an Idempotency-Key. |
| PUT /members/{customerId}/birthday | write_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": "..." } }| Status | Common codes |
|---|---|
| 400 | invalid_json, invalid_customer_id, invalid_points, idempotency_key_required |
| 401 | unauthorized: missing, wrong or revoked key |
| 402 | plan_required: the store isn't on the Plus plan |
| 403 | insufficient_scope: the key doesn't have this access |
| 404 | member_not_found, customer_not_found, reward_unavailable, not_found |
| 409 | request_in_progress, birthday_already_set |
| 422 | insufficient_points, tier_required, invalid_date, idempotency_key_reused |
| 429 | rate_limited, daily_limit |
| 5xx | internal_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
| Event | Sent when |
|---|---|
| member.enrolled | A customer joins the program. |
| points.changed | Points are earned, spent, removed, expired, or released after the pending period (type: release). |
| tier.changed | A member moves to another VIP tier. |
| reward.redeemed | A 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.