E-commerce.

E-commerce integrations usually 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 provides member keys and partner keys separately.

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?

Use the split on purpose.

Why this matters:

• 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.
• Using 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
• what the deficit is for locked rewards
• reward titles and descriptions without exposing partner-management controls

Step 3: Complete checkout and write back the purchase

After payment is captured, 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 the member identifier form your shop already has. 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 is a claim intent, not a direct point deduction. It preserves the platform's staff-confirmed redemption flow.

Voucher checkout flow

When vouchers are part of the checkout:

1. validate with the partner key using POST /partner/vouchers/validate
2. apply the discount in your cart or checkout UI
3. redeem only when the order is finalized

Do not redeem a voucher before the order is confirmed.

Security rules

• Member keys may be used 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

Related topics

• Getting Started
• POS Integration
• Production Checklist
• Member Endpoints