Server-side points (earn & burn)

If your backend awards or spends loyalty points — a stay booked in your own app, a perk redeemed at your front desk — you can credit or debit a member’s AKIN points server-to-server, with no member-side login.

This is a single mutation, recordLoyaltyTransaction, authorised on your x-partner-api-key. It is idempotent: a retry with the same idempotencyKey never double-applies.

Scope required. Unlike the read endpoints, writes require your key to carry the loyalty:write capability scope. A public read-only key is rejected. Ask your AKIN contact to issue (or rotate to) a write-scoped key — see Partner API key scopes .

On Node? The typed Server SDK wraps this — typed input/result, structured errors, rate-limit handling.

Points are network-wide

AKIN points are a single, network-wide balance — not a per-partner wallet. A credit or debit you make moves the member’s balance everywhere and can change their tier at every partner they belong to. Credit points you genuinely own the liability for, and debit only points the member is spending with you.

The mutation

mutation RecordLoyaltyTransaction($input: RecordLoyaltyTransactionInput!) {
  recordLoyaltyTransaction(input: {
    email: "ada@example.com"      # OR memberId, OR externalId — exactly one
    type: CREDIT                  # CREDIT or DEBIT
    points: 500                   # positive magnitude
    reason: "Stay at The Example Hotel"
    idempotencyKey: "booking-9f3c-credit"   # your unique token for this event
  }) {
    transactionId
    memberId
    type
    pointsChange       # signed: +500 for a credit, -500 for a debit
    balance            # member's network-wide balance after the write
    idempotentReplay   # true if this token was already applied (no new write)
  }
}

Send it with your write-scoped partner API key:

curl https://api.akintravel.com/graphql \
  -H "Content-Type: application/json" \
  -H "x-partner-api-key: $AKIN_PARTNER_API_KEY" \
  -d '{
    "query": "mutation($i: RecordLoyaltyTransactionInput!){ recordLoyaltyTransaction(input:$i){ transactionId pointsChange balance idempotentReplay } }",
    "variables": { "i": { "email": "ada@example.com", "type": "CREDIT", "points": 500, "reason": "Stay at The Example Hotel", "idempotencyKey": "booking-9f3c-credit" } }
  }'

Input

There is no partnerId field — the partner is always derived from your API key. You can only act on members enrolled with your program; an unknown member, or one enrolled with a different partner, returns the same MEMBER_NOT_FOUND (so the endpoint can’t be used to probe other partners).

Idempotency

recordLoyaltyTransaction is safe to retry. Scope your idempotencyKey to the real-world event it represents (e.g. booking-<id>-credit, redemption-<id>). On a duplicate:

• No second write happens — the member’s balance is untouched.
• The original transaction is returned, with idempotentReplay: true.
• A replayed debit is not re-checked against the balance, so a retry can’t fail just because the first debit already lowered it.

Debits

A DEBIT is gated on the member’s current balance and never drives it negative. If the member has fewer points than requested, the call fails with a VALIDATION_ERROR naming the current balance and the requested amount, and nothing is written. Debits are pure point spend — they do not create or settle perk-fulfilment records.

Tier changes

A credit (or debit) that crosses a tier threshold recomputes the member’s tier synchronously before the mutation returns, so the balance you get back reflects a settled post-state. Tier-driven side effects (perk cleanup, wallet pass refresh) still run asynchronously.

Rate limits

Writes share your key’s rate limit with reads — the same per-minute budget and burst cap apply.