kudo
Custom plansREST · JSON · HTTPS

API Reference

Read your members, transactions and cards, and record scans, from your own app or back office. The REST API is available on custom plans — contact us to add it.

Browse endpointsAuthentication
Base URL

https://api.kudorewards.co.uk

Auth

Authorization: Bearer lk_live_…

Scopes

read · write

Authentication

Create a key in Settings → Developers → API keys. It is shown once (we store only a SHA-256 hash), so copy it straight away, then send it as a bearer token in the Authorization header on every request.

Authorization: Bearer lk_live_<your_key_here>
  • A key only ever sees its own business.
  • There is no sandbox: every key works on your real data. Give a key the write scope only if it must record scans.

Examples

Read

# List the members of your business
curl https://api.kudorewards.co.uk/api/loyalty-members/ \
  -H "Authorization: Bearer lk_live_<your_key_here>"

Write

# Earn on a member (key needs the "write" scope)
curl -X POST https://api.kudorewards.co.uk/api/scan/ \
  -H "Authorization: Bearer lk_live_<your_key_here>" \
  -H "Content-Type: application/json" \
  -d '{ "member_identifier": "customer@example.com", "value": 1 }'

Endpoints that accept API keys

Every other endpoint refuses API keys with a 403.

Members

GET/api/loyalty-members/List your members. Supports ?search=, ?approval_status= and ?limit=.read scope
GET/api/loyalty-members/<id>/Retrieve one member.read scope

Transactions

GET/api/transactions/List transactions with a summary. Supports ?from=, ?to=, ?type=earn|redeem, ?member_id= and ?location_code=.read scope

Card programs & wallet cards

GET/api/loyalty-programs/List your card programs.read scope
GET/api/loyalty-programs/<id>/Retrieve one card program.read scope
GET/api/wallet/templates/List your wallet cards.read scope
GET/api/wallet/templates/<id>/Retrieve one wallet card.read scope

Scanning

POST/api/scan/Earn or redeem on a member. Body: member_identifier (pass serial, email or phone) plus value, reward_id or preview_only.write scope

Errors you'll see

401 Invalid API keyThe token is wrong or malformed, or the Bearer prefix is missing.
401 API key has been revoked / has expiredCreate a new key in Settings.
403 API keys are not accepted on this endpointOnly the endpoints listed below accept API keys.
403 This API key is read-onlyThe key has no write scope (needed for POST /api/scan/).
403 feature_lockedYour plan doesn't include the REST API, or the subscription has lapsed.

Webhooks

Webhooks (custom plans) are set up in Settings → Developers → Webhooks, not through the API. We POST a signed JSON event for member.created, scan.created, redemption.completed and tier.changed, with an X-Kudo-Signature HMAC-SHA256 header.