E-commerce.

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

Jul 21, 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 and should stay on trusted server infrastructure. 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,
  "note": "Order #WEB-12345"
}

Use whichever member identifier your shop already stores. Email is common, but UUID, member number, and unique identifier also work.

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 submits a claim intent. Points stay untouched until staff confirm the redemption, the platform's standard flow.

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