Merchant login

Language

Ahandee Loyalty

For Developers

Build on our Partner API

Integrate Ahandee Loyalty with your POS, mobile app, or backend. REST for reads and writes, webhooks for real-time loyalty events.

Read the docs Partner dashboard

Everything you need to integrate

Available on merchant plans with Developer access. All traffic is JSON over HTTPS.

  • REST API

    Customers, loyalty cards, stamps, and vouchers — create programs and run day-to-day loyalty operations with JSON everywhere.

  • Webhooks

    Signed HTTPS deliveries when members earn points, collect stamps, or redeem offers.

  • API keys

    Bearer tokens with the lpk_ prefix. Create, rotate, and revoke keys from the partner dashboard.

Reference

API documentation

Authentication, endpoints, webhooks, and error handling for v1.

Overview

The Partner API is available on plans with Developer access. Every request is scoped to your organization.

Base URL

https://loyalty.ahandee.com/api/v1

Version v1 · JSON bodies · UTF-8

Create loyalty cards, stamp cards, and vouchers with POST, or manage them in the partner dashboard. Use nested routes to enroll members, credit points, issue stamps, and redeem vouchers.

Quick start

From zero to your first authenticated request in minutes.

  1. Sign in to the partner dashboard.
  2. Open Developer → API keys and create a named key.
  3. Copy the key immediately — it is shown once and stored as a secure hash.
  4. Send Authorization: Bearer YOUR_KEY on every request.
  5. Optional: configure Webhooks for real-time events.

Authentication

Keys use the lpk_ prefix. Revoked keys return 401. 

# List customers
curl -X GET "https://loyalty.ahandee.com/api/v1/customers?per_page=15" \
  -H "Authorization: Bearer lpk_your_secret_key" \
  -H "Accept: application/json"
# Credit points from a purchase
curl -X POST "https://loyalty.ahandee.com/api/v1/loyalty-cards/12/transactions" \
  -H "Authorization: Bearer lpk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"customer_email":"alex@example.com","reference":"POS-88421","amount":24.50,"currency":"USD"}'

Requests

Headers, idempotency, and response envelopes.

  • Content-Type — application/json for POST bodies.
  • Accept — application/json for responses.
  • Idempotency — Idempotency-Key on POST create and write requests.
  • Pagination — data, meta, links.next.
# Success envelope
{
  "data": { ... },
  "meta": { "request_id": "9f3c2a1e-..." }
}

Endpoints

Paths relative to https://loyalty.ahandee.com/api/v1

Customers

Look up and create customers eligible for your programs.

GET /customers

List customers

Supports ?page=, ?per_page= (max 100), and ?search= (name, email, or phone).

Example request

GET https://loyalty.ahandee.com/api/v1/customers?search=alex&per_page=15

Example response

{
  "data": [
    {
      "id": 1042,
      "name": "Alex Rivera",
      "email": "alex@example.com",
      "phone": "+15551234567",
      "created_at": "2026-04-02T14:30:00+00:00"
    }
  ],
  "meta": {
    "request_id": "9f3c2a1e-8b4d-4e1a-9c2d-1a2b3c4d5e6f",
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  },
  "links": {
    "first": "https://loyalty.ahandee.com/api/v1/customers?page=1",
    "last": "https://loyalty.ahandee.com/api/v1/customers?page=3",
    "prev": null,
    "next": "https://loyalty.ahandee.com/api/v1/customers?page=2"
  }
}
GET /customers/{id}

Retrieve a customer

Example request

GET https://loyalty.ahandee.com/api/v1/customers/1042

Example response

{
  "data": {
    "id": 1042,
    "name": "Alex Rivera",
    "email": "alex@example.com",
    "phone": "+15551234567",
    "created_at": "2026-04-02T14:30:00+00:00"
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
POST /customers

Create or return an existing customer

If the email already exists, the existing profile is returned with HTTP 200.

Example request

POST https://loyalty.ahandee.com/api/v1/customers

{
  "email": "alex@example.com",
  "name": "Alex Rivera",
  "phone": "+15551234567"
}

Example response

{
  "data": {
    "id": 1042,
    "name": "Alex Rivera",
    "email": "alex@example.com",
    "phone": "+15551234567",
    "created_at": "2026-05-16T10:00:00+00:00"
  },
  "meta": {
    "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

Loyalty cards

Create and list cards, enroll customers, and post point transactions.

GET /loyalty-cards

List loyalty cards

Example request

GET https://loyalty.ahandee.com/api/v1/loyalty-cards

Example response

{
  "data": [
    {
      "id": 12,
      "name": "Insider Points",
      "card_identifier": "RIVERSIDE-INSIDER",
      "is_active": true,
      "earn_spend_amount": "10.00",
      "earn_points": 1,
      "earn_currency": "USD",
      "initial_bonus_points": 50,
      "expiry_date": "2027-12-31"
    }
  ],
  "meta": {
    "request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  }
}
POST /loyalty-cards

Create a loyalty card

Omit card_identifier to auto-generate a wallet code. Requires a partner location ID from your account.

Example request

POST https://loyalty.ahandee.com/api/v1/loyalty-cards

{
  "name": "Insider Points",
  "partner_location_id": 2,
  "date_issued": "2026-05-16",
  "earn_spend_amount": 10,
  "earn_points": 1,
  "earn_currency": "USD",
  "initial_bonus_points": 50,
  "is_active": true
}

Example response

{
  "data": {
    "id": 13,
    "name": "Insider Points",
    "card_identifier": "042-118-307-591",
    "is_active": true,
    "earn_spend_amount": "10.00",
    "earn_points": 1,
    "earn_currency": "USD",
    "initial_bonus_points": 50,
    "expiry_date": null
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
GET /loyalty-cards/{id}

Retrieve a loyalty card

Example request

GET https://loyalty.ahandee.com/api/v1/loyalty-cards/12

Example response

{
  "data": {
    "id": 12,
    "name": "Insider Points",
    "card_identifier": "RIVERSIDE-INSIDER",
    "is_active": true,
    "earn_spend_amount": "10.00",
    "earn_points": 1,
    "earn_currency": "USD",
    "initial_bonus_points": 50,
    "expiry_date": "2027-12-31"
  },
  "meta": {
    "request_id": "d4e5f6a7-b8c9-0123-def0-234567890123"
  }
}
POST /loyalty-cards/{id}/enrollments

Enroll a customer on a card

Applies the card initial bonus points when configured.

Example request

POST https://loyalty.ahandee.com/api/v1/loyalty-cards/12/enrollments

{
  "customer_email": "alex@example.com"
}

Example response

{
  "data": {
    "enrollment": {
      "id": 88,
      "customer_id": 1042,
      "loyalty_card_id": 12,
      "created_at": "2026-05-16T10:05:00+00:00"
    },
    "initial_bonus_transactions": [
      {
        "id": 501,
        "type": "bonus",
        "customer_id": 1042,
        "loyalty_card_id": 12,
        "points_delta": 50,
        "points_balance_after": 50,
        "purchase_reference": null,
        "occurred_at": "2026-05-16T10:05:00+00:00"
      }
    ]
  },
  "meta": {
    "request_id": "e5f6a7b8-c9d0-1234-ef01-345678901234"
  }
}
POST /loyalty-cards/{id}/transactions

Credit points from a purchase or adjust balance

Send amount + currency for purchase-based earn rules, or points alone for a manual adjustment.

Example request

POST https://loyalty.ahandee.com/api/v1/loyalty-cards/12/transactions

{
  "customer_email": "alex@example.com",
  "reference": "POS-88421",
  "amount": 24.50,
  "currency": "USD",
  "notes": "Counter sale"
}

Example response

{
  "data": {
    "id": 502,
    "type": "earn",
    "customer_id": 1042,
    "loyalty_card_id": 12,
    "points_delta": 2,
    "points_balance_after": 52,
    "purchase_reference": "POS-88421",
    "occurred_at": "2026-05-16T10:12:00+00:00"
  },
  "meta": {
    "request_id": "f6a7b8c9-d0e1-2345-f012-456789012345"
  }
}

Stamp cards

Create and list stamp cards, then issue stamps after a qualifying purchase.

GET /stamp-cards

List stamp cards

Example request

GET https://loyalty.ahandee.com/api/v1/stamp-cards

Example response

{
  "data": [
    {
      "id": 7,
      "name": "Coffee Club",
      "is_active": true,
      "stamps_required_for_reward": 10,
      "stamps_per_purchase": 1,
      "valid_from": "2026-01-01",
      "valid_until": "2026-12-31"
    }
  ],
  "meta": {
    "request_id": "a7b8c9d0-e1f2-3456-0123-567890123456"
  }
}
POST /stamp-cards

Create a stamp card

Example request

POST https://loyalty.ahandee.com/api/v1/stamp-cards

{
  "name": "Coffee Club",
  "partner_location_id": 2,
  "valid_from": "2026-01-01",
  "valid_until": "2026-12-31",
  "stamps_required_for_reward": 10,
  "stamps_per_purchase": 1,
  "reward_title": "Free coffee",
  "is_active": true
}

Example response

{
  "data": {
    "id": 8,
    "name": "Coffee Club",
    "is_active": true,
    "stamps_required_for_reward": 10,
    "stamps_per_purchase": 1,
    "valid_from": "2026-01-01",
    "valid_until": "2026-12-31"
  },
  "meta": {
    "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}
POST /stamp-cards/{id}/stamps

Issue stamps to a customer

Example request

POST https://loyalty.ahandee.com/api/v1/stamp-cards/7/stamps

{
  "customer_id": 1042,
  "reference": "POS-88422",
  "amount": 5.50,
  "currency": "USD",
  "notes": "Latte purchase"
}

Example response

{
  "data": [
    {
      "id": 301,
      "type": "earn",
      "customer_id": 1042,
      "stamp_card_id": 7,
      "stamps_delta": 1,
      "stamps_balance_after": 4,
      "purchase_reference": "POS-88422",
      "occurred_at": "2026-05-16T10:15:00+00:00"
    }
  ],
  "meta": {
    "request_id": "b8c9d0e1-f2a3-4567-1234-678901234567"
  }
}

Vouchers

Create and list vouchers, then redeem them for a customer at checkout.

GET /vouchers

List vouchers

Example request

GET https://loyalty.ahandee.com/api/v1/vouchers

Example response

{
  "data": [
    {
      "id": 3,
      "name": "Spring Savings",
      "voucher_code": "SPRING20",
      "is_active": true,
      "discount_type": "percent",
      "discount_value": "20.00",
      "valid_from": "2026-03-01",
      "valid_until": "2026-05-31"
    }
  ],
  "meta": {
    "request_id": "c9d0e1f2-a3b4-5678-2345-789012345678"
  }
}
POST /vouchers

Create a voucher

voucher_code must be unique within your organization (letters, numbers, dashes, underscores).

Example request

POST https://loyalty.ahandee.com/api/v1/vouchers

{
  "name": "Spring Savings",
  "partner_location_id": 2,
  "voucher_code": "SPRING20",
  "valid_from": "2026-03-01",
  "valid_until": "2026-05-31",
  "discount_type": "percent",
  "discount_value": 20,
  "is_active": true
}

Example response

{
  "data": {
    "id": 4,
    "name": "Spring Savings",
    "voucher_code": "SPRING20",
    "is_active": true,
    "discount_type": "percent",
    "discount_value": "20.00",
    "valid_from": "2026-03-01",
    "valid_until": "2026-05-31"
  },
  "meta": {
    "request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  }
}
POST /vouchers/{id}/redeem

Redeem a voucher for a customer

Example request

POST https://loyalty.ahandee.com/api/v1/vouchers/3/redeem

{
  "customer_email": "alex@example.com",
  "order_amount": 45.00,
  "order_reference": "POS-88423",
  "partner_location_id": 2,
  "notes": "In-store checkout"
}

Example response

{
  "data": {
    "id": 19,
    "voucher_id": 3,
    "customer_id": 1042,
    "voucher_code": "SPRING20",
    "order_amount": "45.00",
    "discount_amount": "9.00",
    "order_reference": "POS-88423",
    "redeemed_at": "2026-05-16T10:18:00+00:00"
  },
  "meta": {
    "request_id": "d0e1f2a3-b4c5-6789-3456-890123456789"
  }
}

Webhooks

Signed HTTPS deliveries when members interact with your programs.

# Delivery headers
Content-Type: application/json
X-Loyalty-Event: loyalty.points_earned
X-Loyalty-Timestamp: 1715789400
X-Loyalty-Signature: <hmac-sha256-hex>

Verify with HMAC-SHA256(timestamp + "." + raw_body, signing_secret) 

# Payload
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "loyalty.points_earned",
  "created_at": "2026-05-16T12:00:00+00:00",
  "data": { ... }
}

Event types

Event Description
customer.created A new customer profile is linked to your organization.
customer.updated Customer profile or enrollment details change.
loyalty.enrolled A customer enrolls on a loyalty card.
loyalty.points_earned Points are credited from a purchase or bonus.
loyalty.points_redeemed Points are spent on a reward or redemption.
loyalty.reward_claimed A customer claims a loyalty reward.
stamp.issued A stamp is added to a customer stamp card.
stamp.reward_fulfilled A stamp card reward is marked fulfilled.
voucher.redeemed A voucher is redeemed at a location.
referral.completed A referral program milestone is completed.

Errors

Consistent JSON error objects across the API.

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": { "email": ["The email field is required."] }
  }
}
HTTP Meaning
400 Bad request — Validation failed or malformed JSON body.
401 Unauthorized — Missing or invalid API key.
403 Forbidden — Key is valid but not allowed for this resource or plan.
404 Not found — Resource does not exist or is outside your organization.
429 Too many requests — Rate limit exceeded — retry with exponential backoff.
500 Server error — Unexpected failure — contact support if it persists.