Happy Rewards Logo
API Docs
X-API-Key: No Key
API Reference Documentation • Live Interactive Console

Happy Rewards API Documentation

Base: https://docs.happyrewards.io/api

The Happy Rewards API is a comprehensive RESTful loyalty and rewards engine. It enables customer profile management, digital loyalty and membership cards issuance, balance score tracking, and automated rewards redemption. All endpoints consume and output standard JSON payloads.

Parameter Legend:
Required Mandatory — validation error if omitted
Either / Or At least one of the marked fields must be present
Optional Safe to omit — defaults applied
Authentication: X-API-Key Required on All Endpoints

Authentication

Authenticate all incoming HTTP requests via API Key

Mandatory

The API relies on API key authentication via the X-API-Key request header. When testing in this documentation, paste your key once in the top bar and every live test will automatically include it.

Header: X-API-Key : YOUR_API_KEY_HERE

HTTP Status Codes & Responses

Standard HTTP response status codes returned by the API:

Status Meaning Description
200 OKSuccessStandard successful request and response.
201 CreatedResource CreatedA new customer profile or card has been successfully issued.
400 Bad RequestInvalid Request / Card TypeMalformed request or unsupported card operation type.
401 UnauthorizedAuthentication FailedMissing or invalid X-API-Key header.
422 UnprocessableValidation ErrorMissing mandatory parameters (e.g. neither phone nor email provided, missing templateId).
500 Server ErrorInternal Server ErrorAn unexpected server error occurred while processing the request.

Customers API

Manage customer identities, phone records, and profile details

Prefix: /api/customers
GET /api/customers
List all customer profiles with optional query filters

Query Parameters

All parameters in this request are optional query filters.

phone string

Filter customer by phone number

Optional
email string

Filter customer by email address

Optional
page integer

Page offset (defaults to 1)

Optional
itemsPerPage integer

Page size limit (defaults to 20)

Optional
Live Request Console Ready
POST /api/customers
Either Phone or Email is Mandatory Create customer profile

Request Body Schema

At least one contact identifier (phone or email) must be supplied.

Field Type Status Description
phone * string Required if no email Mobile phone (e.g. +1234567890)
email * email Required if no phone Valid email address
firstName string Optional First name
surname string Optional Last / Family name
gender integer Optional 0 = None, 1 = Male, 2 = Female
dateOfBirth string Optional YYYY-MM-DD
externalUserId string Optional External CRM identifier
JSON Payload
GET /api/customers/{id}
Retrieve individual customer profile by ID

Path Parameters

id string | integer

Unique customer ID to retrieve

Required
Path Parameter
PATCH /api/customers/{id}
Modify existing customer profile fields

Parameters

id path • string
Required

Provide only the fields you wish to update in the JSON request body (all body fields are optional).

Request Body (JSON)
DELETE /api/customers/{id}
Remove a customer record permanently

Path Parameters

id string

Customer ID to permanently delete

Required

Cards API

Issue and inspect customer loyalty, reward, and stamp cards

Prefix: /api/cards
GET /api/cards
List all cards with optional filters

Query Parameters

templateId integer
Optional
customerPhone string
Optional
customerEmail string
Optional
POST /api/cards
templateId & customerId Mandatory Create card for customer

Request Body Schema

2 required, 1 optional

Issue a digital loyalty, stamp, or membership card directly linked to a registered customer.

Field Type Status Description
templateId * integer > 0 Required ID of the digital card template
customerId * string Required ID of the customer for whom the card is created
customFields array<object> Optional Array of objects with id (integer) and value (string). Can exclude optional fields or fields filled in customer (phone, email, FName, SName, DateOfBirth).
JSON Payload
GET /api/cards/{id}
Get specific card details

Path Parameters

id string

Unique Card Number or ID

Required
DELETE /api/cards/{id}
Deactivate or remove a digital card

Path Parameters

id string

Target card number to deactivate

Required

Templates API

Inspect card templates, visual appearances, custom fields, tiers, and installation links

Prefix: /api/templates
GET /api/templates
All Query Parameters Optional

Query Parameters

Parameter Type Status Description
page integer Optional Pagination page number (default: 1)
itemsPerPage integer Optional Number of templates per page (default: 10, max: 100)
GET /api/templates/{id}
id is Mandatory Get template configuration and fields

Path Parameters

id * path • integer / string

ID or hash of the digital card template

Required

Returns template metadata, customFields definitions (for card creation), reward tiers, membership tiers, appearance settings, and Apple/Google Wallet install and QR links.

Transactions & Loyalty Operations

Accrue points, deduct balances, assign rewards, and handle redemptions

Prefix: /api/cards/*
POST /api/cards/add-scores
card_number is Mandatory ScoreCardService

Request Body Schema

Field Type Status Description & Default
card_number * string Required Target card identifier
scores numeric Optional Score points to credit (default: 0)
purchase_sum numeric Optional Purchase amount (default: 0)
comment string Optional Transaction description
JSON Payload
POST /api/cards/subtract-scores
card_number is Mandatory ScoreCardService

Request Body Schema

Field Type Status Description & Default
card_number * string Required Target card identifier
scores numeric Optional Points to deduct (default: 0)
purchase_sum numeric Optional Purchase amount (default: 0)
comment string Optional Transaction note
JSON Payload
POST /api/cards/recieve-rewards
card_number & id Mandatory RewardCardService

Request Body Schema

Field Type Status Description
card_number * string Required Target card identifier
id * string Required Reward Item ID to claim (e.g. REWARD-101)
purchase_sum numeric Optional Purchase value (default: 0)
comment string Optional Redemption note
JSON Payload