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 access resources created by that partner and no other
• Canonical API contracts. The platform validates requests 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. POS integrations spend most of their calls here.

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

You can pass any of these formats and the API will resolve the member. This flexibility matters for POS systems that may have nothing but a customer email or loyalty number.

You can also pass a points field (integer) to override the automatic point calculation. This is useful for custom promotions or manual adjustments. The card's max_points_per_purchase still caps the override after tier multipliers, so you can never exceed the configured maximum.

The staff_id is optional. It attributes the transaction to a specific staff member for reporting. Without it, the platform attributes the transaction 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 platform attributes the redemption to "System". This enables headless integrations (Shopify, WooCommerce) that do not have staff accounts.

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

Deduct points (custom deduction)

POST /api/agent/v1/partner/transactions/deduct

Scope: write:transactions

{
  "card_id": "uuid-of-loyalty-card",
  "member_identifier": "[email protected]",
  "points": 500,
  "note": "Gift card redemption - $50 Amazon card",
  "reference": "giftcard:order:12345",
  "staff_id": "uuid-of-staff-member"
}

Deducts a custom number of points from a member's card balance. The deduction consumes points in FIFO order (oldest first). Deductions require a note for the audit trail.

Use this for off-platform rewards like gift cards or external services, without needing a reward object.

The reference field is optional. It links the deduction to an external system for reconciliation.

The staff_id is optional. If you omit it, the platform records the transaction as "Partner".

A deduction fails with INSUFFICIENT_POINTS if the member does not have enough points. The tier system ignores deductions.

Successful deduction responses include transaction_id, points_deducted, member_balance, new_balance, card_id, and member_id.

---

Members

Member endpoints are read for partner keys, no writes. The agent API cannot create or modify members. They self-register through the platform.

List and detail return only members who have interacted with your business: earned points, collected a stamp, redeemed a voucher, or used a pass. A member who joined a card but has no interaction yet answers not-found, indistinguishable from an unknown id. The transaction endpoints accept that member's identifier regardless. See First-time customers.

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, nothing more: id, unique_identifier, name, email, locale, currency, time_zone, last_login_at, created_at, updated_at, avatar, is_anonymous.

---

Achievements

A read-only view of the partner's achievements program. Program settings change in the partner dashboard, not through the API. Both endpoints require the achievements feature (achievements_permission, from the plan or the per-partner override); without it they answer 403.

Get the program

GET /api/agent/v1/partner/achievements

Scope: read

Returns the program (status of active, paused, or inactive, whether a history import is running, activated_at, week_starts_on, and the catalog version), the configured rules (per achievement: key, name, group, threshold, enabled, and the reward's public envelope of type, cap, and window, never the linked product), and aggregate insights while the program is active: members with an achievement, awards in the last 30 days, weekly-run and near-milestone counts, and reward usage. Insights are aggregates only, never member listings.

Get a member's achievements

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

Scope: read

Returns one member's progress at this business (loyalty days, current and best weekly run, the last qualifying week, distinct loyalty options used, first and last activity) and their paginated earned achievements, each with key, name, group, origin (live, or backfill for an achievement recognized by the history import), earned date, and a safe reward state (none, pending, delivered, or failed). Only members with a relationship at this business resolve; anyone else answers not-found. Voided achievements never appear.

---

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.

A single call adds up to one full card (stamps_required) when the card has no per-transaction cap, or up to the configured cap otherwise. The absolute ceiling is 100.

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 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. The platform generates one when you omit it.

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

---

Prepaid passes

Prepaid passes are products your staff sell at the counter: a 10-visit pack or a time-limited unlimited membership. Templates are prepaid-passes; sold instances are member-passes. Price fields are in minor units (cents).

List pass templates

GET /api/agent/v1/partner/prepaid-passes

Scope: read or write:passes

Get pass template

GET /api/agent/v1/partner/prepaid-passes/{id}

Scope: read or write:passes

Create pass template

POST /api/agent/v1/partner/prepaid-passes

Scope: write:passes

Set uses_total for a counted pass, or omit it and set validity_days (1 to 366) for an unlimited pass.

Update pass template

PUT /api/agent/v1/partner/prepaid-passes/{id}

Scope: write:passes

Delete pass template

DELETE /api/agent/v1/partner/prepaid-passes/{id}

Scope: write:passes

Soft-deletes the template so future sales stop. Passes already sold keep working.

Sell a pass

POST /api/agent/v1/partner/prepaid-passes/{id}/sell

Scope: write:passes

Issues a sold instance to a member. Body: member_identifier (required), optional price_paid (cents; defaults to the template price), optional staff_id (a staff member in the pass's club). With no staff attached, the ledger entry records source: agent_api plus the agent key id.

List a member's passes

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

Scope: read or write:passes

Returns the member's sold passes in your clubs. Use it to find a member-pass id before scanning or undoing.

Get a sold pass

GET /api/agent/v1/partner/member-passes/{memberPassId}

Scope: read or write:passes

Returns the sold pass with its ledger history.

Scan a visit

POST /api/agent/v1/partner/member-passes/{memberPassId}/scan

Scope: write:passes

Deducts one or more visits. Body: optional quantity (default 1), optional staff_id. Counted passes lose quantity visits; unlimited passes record the visit only.

Undo the last visit

POST /api/agent/v1/partner/member-passes/{memberPassId}/undo

Scope: write:passes

Writes an offsetting ledger entry and restores the balance. Fails when there is no visit to undo.

---

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