Plug Software
Loyalvia로 돌아가기
문서 메뉴

프로그램 운영

API 및 웹훅

자체 시스템이나 사용 중인 다른 앱이 로열티 프로그램을 읽고 업데이트하게 하세요. 모바일 앱에 잔액을 표시하거나, 리뷰에 포인트를 주거나, 회원이 새 등급에 도달하면 반응할 수 있습니다.

참고: API와 웹훅은 Plus 요금제에 포함됩니다. 얼리버드 스토어는 Pro의 모든 기능을 무료로 이용하지만, Plus는 별도의 유료 요금제입니다. 요금제 및 결제를 참고하세요.

만들 수 있는 것

  • 포인트, 내역, 리워드를 보여 주고 교환하는 모바일 앱이나 헤드리스 스토어.
  • 다른 앱의 포인트: 리뷰, 퀴즈, 스토어 이벤트, 자체 백오피스.
  • 잔액과 등급을 이메일, 헬프데스크, CRM 도구에 동기화.

API 키 만들기

  1. 앱 메뉴에서 API 및 웹훅으로 이동합니다.
  2. API 키 만들기의 이름에 사용할 곳을 입력합니다(예: “모바일 앱” 또는 다른 앱 이름).
  3. 권한에서 필요한 것만 선택하고 키 만들기를 클릭합니다.
  4. 키를 바로 복사하세요. 한 번만 표시되며, 분실하면 취소하고 새로 만드세요.
설정설명
읽기프로그램 설정, 회원, 포인트 내역, 리워드, 등급.
포인트 추가 및 차감회원 잔액 조정.
리워드 교환회원의 포인트로 리워드를 교환하고 할인 코드 생성.
회원 관리고객 등록 및 생일 저장.
중요: 키는 비밀로 유지하세요. 서버에서만 사용하고, 누구나 복사할 수 있는 모바일 앱이나 스토어 코드에는 절대 넣지 마세요. 키가 유출되면 바로 옆의 취소를 클릭하세요. 키는 최대 10개까지 만들 수 있으며, 앱을 삭제하면 모두 취소됩니다.

웹훅 엔드포인트 추가

웹훅은 일이 생기는 즉시 서버에 알려 주므로 계속 조회할 필요가 없습니다.

  1. API 및 웹훅의 엔드포인트 추가에서 엔드포인트 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를 호출하고 웹훅을 받는 데 필요한 모든 것.

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