E-commerce.

Build a webshop or checkout integration using member keys for wallet access and partner keys for purchase writeback.

Oct 4, 2026

E-commerce integrations need two different trust levels:

read access to one member's personal wallet
write access to partner-owned loyalty operations after payment

That is why the API splits access into member keys and partner keys.

Note: For WooCommerce stores, use the native WooCommerce integration. It is plugin-free and needs no API development. This guide serves custom storefronts and other platforms.

Why two keys exist

Use the split on purpose.

Key	What It Should Do
Member key	Read the member's wallet, cards, rewards, and profile
Partner key	Award points, redeem rewards, validate vouchers, and perform business-owned writes

A member key is self-scoped and cannot mutate partner resources. A partner key can perform business actions when its scopes grant them and should stay on trusted server infrastructure. The Partner key creation form selects View only; choose the write preset required by your checkout before creating the key. One partner key for everything overexposes capabilities and makes least privilege impossible.

Recommended architecture

sequenceDiagram
    participant Browser as Member Browser
    participant Shop as Shop Backend
    participant RL as Reward Loyalty Agent API

    Browser->>Shop: Login / checkout session
    Shop->>RL: GET /member/balance (member key)
    RL-->>Shop: Wallet balances
    Shop->>RL: GET /member/rewards (member key)
    RL-->>Shop: Redeemable rewards
    Browser->>Shop: Completes payment
    Shop->>RL: POST /partner/transactions/purchase (partner key)
    RL-->>Shop: Points awarded
    Shop-->>Browser: Updated loyalty confirmation

Step 1: Load wallet data with the member key

GET /api/agent/v1/member/balance HTTP/1.1
Host: your-domain.com
Accept: application/json
X-Agent-Key: rl_member_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8

{
  "error": false,
  "data": [
    {
      "card_id": "3598a5db-f008-477c-ac4d-5365c662ad62",
      "card_title": "Coffee Rewards",
      "balance": 420,
      "currency": "USD"
    }
  ]
}

Step 2: Show redeemable rewards

GET /api/agent/v1/member/rewards?per_page=25 HTTP/1.1
Host: your-domain.com
Accept: application/json
X-Agent-Key: rl_member_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8

This lets the storefront show what the member can afford now and the deficit for locked rewards, with reward titles and descriptions but no partner-management controls.

Step 3: Complete checkout and write back the purchase

After you capture payment, award the points from your backend with the partner key.

POST /api/agent/v1/partner/transactions/purchase HTTP/1.1
Host: your-domain.com
Accept: application/json
Content-Type: application/json
X-Agent-Key: rl_agent_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0

{
  "card_id": "3598a5db-f008-477c-ac4d-5365c662ad62",
  "member_identifier": "[email protected]",
  "purchase_amount": "84.90",
  "source_reference": "web:store-1:WEB-12345",
  "currency": "USD",
  "source_completed_at": "2026-09-16T09:41:07Z",
  "note": "Order #WEB-12345"
}

Use the member UUID, email, member number, or unique identifier your shop stores. Set currency to the card currency and source_completed_at to the actual payment time, with whole seconds. Reuse the same source_reference and sale facts for every retry. See the purchase contract for time limits and response codes.

Optional: Member claim flow

If your storefront lets the member request a reward before or after checkout, use the member claim endpoint:

POST /api/agent/v1/member/rewards/{rewardId}/claim HTTP/1.1
Host: your-domain.com
Accept: application/json
X-Agent-Key: rl_member_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8

This endpoint checks the member's reward eligibility and returns claim_submitted. It does not deduct points, save a pending claim, or notify staff. Your integration must arrange the staff handoff and use the normal redemption workflow to complete it.

Voucher checkout flow

When vouchers are part of the checkout:

validate with the partner key using POST /partner/vouchers/validate
apply the discount in your cart or checkout UI
redeem only when the order is final

Security rules

Member keys belong in member-scoped application flows.
Partner keys should live only on the server.
Never send a partner key to the browser.
Use separate partner keys for storefront writes and operational jobs when possible.

Failure cases to handle

At minimum, build logic for:

AUTH_INSUFFICIENT_SCOPE
RATE_LIMITED
NOT_FOUND for missing cards or members
VALIDATION_FAILED
FEATURE_DISABLED