Partner Endpoints.

All partner endpoints are prefixed with /api/agent/v1/partner and require a partner-scoped key (rl_agent_).

Common Patterns

All partner endpoints share these behaviors:

• Multi-tenant isolation — A partner key can only access resources created by that partner
• Canonical API contracts — Requests are validated against the live agent schema, permission gates, and ownership checks
• JSON request/response — Send and receive application/json
• Pagination — List endpoints support ?page=1&per_page=25 query parameters

Health Check

GET /api/agent/v1/health

Available to all key roles. Returns key identity, scopes, and owner information. Use this to verify your key works before making other requests.

No scope required.

Clubs

Clubs organize a partner's staff and operations. Most resources (cards, staff) belong to a club.

List Clubs

GET /api/agent/v1/partner/clubs

Scope: read or write:clubs

Get Club

GET /api/agent/v1/partner/clubs/{id}

Scope: read or write:clubs

Create Club

POST /api/agent/v1/partner/clubs

Scope: write:clubs

{
  "name": "Downtown Location",
  "description": "Our flagship store"
}

Update Club

PUT /api/agent/v1/partner/clubs/{id}

Scope: write:clubs

Delete Club

DELETE /api/agent/v1/partner/clubs/{id}

Scope: write:clubs

Loyalty Cards

Loyalty cards define point-earning rules and associated rewards.

List Cards

GET /api/agent/v1/partner/cards

Scope: read or write:cards

Get Card

GET /api/agent/v1/partner/cards/{id}

Scope: read or write:cards

Create Card

POST /api/agent/v1/partner/cards

Scope: write:cards

Update Card

PUT /api/agent/v1/partner/cards/{id}

Scope: write:cards

Delete Card

DELETE /api/agent/v1/partner/cards/{id}

Scope: write:cards

Rewards

Rewards are what members save up for. Each reward belongs to a loyalty card.

List Rewards

GET /api/agent/v1/partner/rewards

Scope: read or write:rewards

Get Reward

GET /api/agent/v1/partner/rewards/{id}

Scope: read or write:rewards

Create Reward

POST /api/agent/v1/partner/rewards

Scope: write:rewards

Update Reward

PUT /api/agent/v1/partner/rewards/{id}

Scope: write:rewards

Delete Reward

DELETE /api/agent/v1/partner/rewards/{id}

Scope: write:rewards

Transactions

Transactions handle the core earn-and-burn flow. These are the most critical endpoints for POS integrations.

List Transactions

GET /api/agent/v1/partner/transactions

Scope: read or write:transactions

Lists transactions for your partner account, newest first. Supports the following query parameters:

Record a Purchase (Award Points)

POST /api/agent/v1/partner/transactions/purchase

Scope: write:transactions

{
  "card_id": "uuid-of-loyalty-card",
  "member_identifier": "[email protected]",
  "purchase_amount": 24.50,
  "staff_id": "uuid-of-staff-member",
  "note": "Coffee and pastry"
}

Member identification — The member_identifier field accepts multiple formats:

• Member UUID
• Email address
• Member number
• Unique identifier

The system resolves the member automatically. This flexibility is critical for POS systems that may only have a customer email or loyalty number.

The staff_id is optional—it attributes the transaction to a specific staff member for reporting. Without it, the transaction is attributed to "System".

Redeem a Reward (Deduct Points)

POST /api/agent/v1/partner/transactions/redeem

Scope: write:rewards

{
  "card_id": "uuid-of-loyalty-card",
  "reward_id": "uuid-of-reward",
  "member_identifier": "[email protected]",
  "staff_id": "uuid-of-staff-member"
}

The staff_id is optional. Without it, the redemption is attributed to "System"—this enables headless integrations (Shopify, WooCommerce) that don't have staff accounts.

Successful redemption responses include transaction_id, points_deducted, member_balance, new_balance, reward_id, reward, card_id, and member_id.

Members

Member endpoints are read-only for partner keys. Members cannot be created or modified via the agent API—they self-register through the platform.

List Members

GET /api/agent/v1/partner/members

Scope: read

Get Member

GET /api/agent/v1/partner/members/{id}

Scope: read

Get Member Balance

GET /api/agent/v1/partner/members/{id}/balance/{cardId}

Scope: read

Returns the member's point balance for a specific loyalty card.

Member list/detail responses expose the hardened public payload only: id, unique_identifier, name, email, locale, currency, time_zone, last_login_at, created_at, updated_at, avatar, is_anonymous.

Stamp Cards

Stamp cards work like digital punch cards. Members collect stamps and earn a reward when the card is complete.

List Stamp Cards

GET /api/agent/v1/partner/stamp-cards

Scope: read or write:stamps

Get Stamp Card

GET /api/agent/v1/partner/stamp-cards/{id}

Scope: read or write:stamps

Create Stamp Card

POST /api/agent/v1/partner/stamp-cards

Scope: write:stamps

Update Stamp Card

PUT /api/agent/v1/partner/stamp-cards/{id}

Scope: write:stamps

Delete Stamp Card

DELETE /api/agent/v1/partner/stamp-cards/{id}

Scope: write:stamps

Add Stamps

POST /api/agent/v1/partner/stamp-cards/{id}/stamps

Scope: write:stamps

Award stamps to a member on a specific stamp card.

Redeem Stamp Reward

POST /api/agent/v1/partner/stamp-cards/{id}/redeem

Scope: write:stamps

Redeem the stamp card reward when a member has collected all required stamps.

Use canonical create/update fields: stamps_expire_days and requires_physical_claim.

Vouchers

Vouchers provide instant-value discounts through promotional codes.

List Vouchers

GET /api/agent/v1/partner/vouchers

Scope: read or write:vouchers

Get Voucher

GET /api/agent/v1/partner/vouchers/{id}

Scope: read or write:vouchers

Create Voucher

POST /api/agent/v1/partner/vouchers

Scope: write:vouchers

Update Voucher

PUT /api/agent/v1/partner/vouchers/{id}

Scope: write:vouchers

Delete Voucher

DELETE /api/agent/v1/partner/vouchers/{id}

Scope: write:vouchers

Validate Voucher Code

POST /api/agent/v1/partner/vouchers/validate

Scope: write:vouchers

Check if a voucher code is valid and redeemable without actually redeeming it.

Use canonical voucher fields: type, value, valid_from, valid_until, max_uses_total, and max_uses_per_member. code is optional on create and is generated automatically when omitted.

Validate request body:

• code
• member_identifier
• club_id
• order_amount (optional, minor units)

Validate response fields:

• valid
• voucher_id
• code
• name
• type
• value
• currency
• discount_amount
• capped
• original_amount
• final_amount
• times_used
• remaining_uses
• valid_until

Redeem Voucher

POST /api/agent/v1/partner/vouchers/{id}/redeem

Scope: write:vouchers

Redeem request body:

• member_identifier
• order_amount (optional, minor units)
• order_reference (optional)

Redeem response fields:

• voucher_id
• code
• type
• member_id
• discount_amount
• points_awarded
• remaining_uses
• redemption_id

Tiers

Membership tiers define VIP levels with multipliers and benefits.

List Tiers

GET /api/agent/v1/partner/tiers

Scope: read or write:tiers

Get Tier

GET /api/agent/v1/partner/tiers/{id}

Scope: read or write:tiers

Create Tier

POST /api/agent/v1/partner/tiers

Scope: write:tiers

Use the canonical tier threshold field: points_threshold.

Update Tier

PUT /api/agent/v1/partner/tiers/{id}

Scope: write:tiers

Delete Tier

DELETE /api/agent/v1/partner/tiers/{id}

Scope: write:tiers

Staff

Manage staff members who process transactions at partner locations.

List Staff

GET /api/agent/v1/partner/staff

Scope: read or write:staff

Get Staff Member

GET /api/agent/v1/partner/staff/{id}

Scope: read or write:staff

Create Staff Member

POST /api/agent/v1/partner/staff

Scope: write:staff

Use the canonical staff assignment field: club_id.

Staff list/detail responses expose: id, club_id, club_name, name, email, locale, time_zone, number_of_times_logged_in, last_login_at, created_at, updated_at, avatar.

Update Staff Member

PUT /api/agent/v1/partner/staff/{id}

Scope: write:staff

Delete Staff Member

DELETE /api/agent/v1/partner/staff/{id}

Scope: write:staff

Related Topics

• Scopes & Permissions — Which scopes are required for each endpoint
• Error Handling — Understanding error responses
• Authentication — Key format and security model