Integrate Engage with your checkout system — POS, e-commerce, or manual order processing. The unified API generates both receipt and sticker codes using the same powerful backend function.
This API works for any business with a checkout process. Whether you're a coffee shop, an online store, or a service provider, you can generate codes for your customers.
POS Systems
Restaurants, cafes, retail stores — generate codes on receipt
E-Commerce
Online stores, Shopify, WooCommerce — generate codes after checkout
Manual Checkout
Phone orders, events, pop-ups — generate codes manually
Unified Code Generator: Both receipt codes and sticker codes use the same business code generator. function. This ensures consistency across all code types and makes it easy to switch between sticker and receipt models.
/api/business/receipt/generateBREW-PR-00042-A7X9/api/business/receipt/sticker-batchBREW-PS-00001-A7X9Both use the same underlying system with different code subtype values: "R" for Receipt or "S" for Sticker.
All API requests that modify data require an API key. You can find your API key in your business settings under Settings → Engagement → POS Receipt Points.
Include the key in the request header:
x-api-key: engage_live_abc123def456...Keep your API key secret
Never expose your API key in client-side code. All API calls should be made from your server. Regenerate your key anytime from your dashboard if compromised.
Engage does not record your sales data. We only need the cart total to calculate points. The items array and other fields are optional for your own records.
amount — Cart total (KES)unlocks — What customer gets (default: "points")pointsOverride — Set exact pointsitems — Line items (for your records)customerPhone — Pre-fill customer infotransactionId — Your order/receipt referencePoints Calculation: Points = Cart Amount × Your Business Multiplier
Example: Cart total = KES 250, Multiplier = 2.0 → Customer gets 500 points
Use the unlocks parameter to control exactly what your customer gets. This lets you tailor the experience based on purchase value or promotional strategy.
Points Only
Earn points, need another code to access features
Small purchases, building loyalty
Spin Access
Unlock the spin wheel immediately
Mid-tier purchases, instant rewards
Draw Entry
Auto-entry into prize draws
Promotional periods, building anticipation
Spin + Draw (Premium)
Both spin access AND draw entry
High-value purchases, VIP customers
"unlocks": "points" — customer earns points, needs to come back"unlocks": "spin" — customer can spin immediately"unlocks": "spin_draw" — premium experience rewards loyalty"unlocks": "draw" — build excitement for upcoming events/api/business/receipt/generateAPI KeyPro & EnterpriseGenerate a unique receipt code for a customer purchase. Works with POS systems, e-commerce stores, and any checkout process. The unified code generator handles both receipts and stickers with the same underlying function.
Request
{
"amount": 250.00, // Required: Cart total in KES
"items": [ // Optional: Line items for your records
{
"name": "Latte",
"qty": 2,
"price": 125.00
}
],
"cashier": "Jane", // Optional: Staff or order reference
"unlocks": "spin", // Optional: "points" | "spin" | "draw" | "spin_draw" (default: "points")
"customerPhone": "0712345678", // Optional: Pre-fill customer info
"pointsOverride": 500, // Optional: Set exact points instead of calculated
"transactionId": "ORD-12345", // Optional: Your system's order/receipt ID
"storeLocation": "Nairobi" // Optional: Store location
}Response
{
"success": true,
"receipt": {
"code_id": "uuid",
"receipt_id": "uuid",
"receipt_number": "RCPT-0042",
"code": "BREW-PR-00042-A7X9",
"points_earned": 500,
"amount": 250.00,
"unlocks": "spin",
"tier": "standard",
"business_name": "Brew & Bean Coffee",
"business_slug": "brew-bean",
"business_logo": "https://...",
"business_color": "#8B5CF6",
"qr_url": "/spin?code=BREW-PR-00042-A7X9"
}
}Notes
/api/code/lookupNone (public)All PlansValidate a code and get its details. Works for both receipt codes and sticker codes. Useful for checking if a code is still valid before using it in your system.
Request
GET /api/code/lookup?code=BREW-PR-00042-A7X9
Response
{
"success": true,
"code": "BREW-PR-00042-A7X9",
"unlocks": "spin",
"type": "receipt", // or "sticker", "public"
"tier": "standard", // or "bronze", "silver", "gold", "diamond"
"point_value": 500,
"business_id": "uuid",
"business_name": "Brew & Bean Coffee",
"business_slug": "brew-bean",
"business_logo": "https://...",
"business_color": "#8B5CF6",
"redirect_url": "/brew-bean/spin",
"is_active": true, // or false
"max_uses": 1,
"current_uses": 0,
"max_uses_per_user": 1,
"valid_from": "2026-07-18 09:21:11.069601+00",
"valid_until": "2030-07-18 09:21:11.069601+00",
}Notes
/api/business/customers/lookupAPI Key (X-API-Key header)Pro & EnterpriseFind a customer by phone, email, or ID number. Useful for POS and e-commerce checkout to verify the customer and retrieve their points balance.
Request
{
"phone": "+254700000000", // OR
"email": "customer@email.com", // OR
"id_number": "12345678"
}Response
{
"success": true,
"users": [
{
"id": "uuid",
"email": "customer@email.com",
"full_name": "Jane Doe",
"phone": "+254700000000",
"id_number": "12345678",
"status": "active",
"id_verified": true,
"summary": {
"businesses": [
{
"business_id": "uuid",
"business_name": "Brew & Bean",
"points": 500,
"tier": "silver",
"spins_used": 3,
"is_active": true
}
],
"recent_spins": [...]
}
}
]
}Notes
/api/business/customers/points/deductAPI Key (X-API-Key header)Pro & EnterpriseDeduct points from a customer's balance for a purchase. This is how POS and e-commerce checkout works — the customer pays with points, and the business deducts them server-side.
Request
{
"user_id": "uuid", // Required: Customer user ID
"points": 100, // Required: Points to deduct
"reference_id": "ORD-12345", // Optional: Your order/receipt ID
"description": "Coffee purchase" // Optional: Transaction description
}Response
{
"success": true,
"transaction": {
"id": "uuid",
"user_id": "uuid",
"points_change": -100,
"current_points": 400,
"transaction_type": "pos_deduction",
"description": "Coffee purchase",
"created_at": "2026-07-30T10:00:00Z"
}
}Notes
/api/notifications/sendAdmin Session or Business API KeyAll PlansSend an in-app notification to a user, optionally with email and SMS. Used by Engage for important system events. Businesses handle their own marketing outside Engage.
Request
{
"user_id": "uuid",
"type": "system_alert",
"title": "Important Update",
"message": "Your account has been verified.",
"business_id": "uuid", // Optional
"email": "user@email.com", // Optional
"phone": "+254700000000", // Optional
"email_html": "<p>HTML content</p>", // Optional
"sms_body": "SMS text", // Optional
"metadata": {} // Optional
}Response
{
"success": true,
"results": {
"inApp": true,
"email": true,
"sms": false
},
"notification": {
"user_id": "uuid",
"business_id": "uuid",
"type": "system_alert",
"title": "Important Update",
"message": "Your account has been verified."
}
}Notes
After payment is complete, POS sends cart total and unlocks based on order size:
POST /api/business/receipt/generate
{
"amount": 250.00,
"items": [
{ "name": "Burger", "qty": 1, "price": 150.00 },
{ "name": "Fries", "qty": 1, "price": 50.00 },
{ "name": "Soda", "qty": 1, "price": 50.00 }
],
"registerId": "REG-001",
"cashier": "Jane",
"unlocks": "spin",
"customerPhone": "0712345678"
}Customer gets code printed on receipt, can spin the wheel. Uses unified generator with subtype "R".
After order confirmation, webhook sends cart total and unlocks based on order value:
POST /api/business/receipt/generate
{
"amount": 500.00,
"items": [
{ "name": "T-Shirt", "qty": 2, "price": 250.00 }
],
"transactionId": "ORD-12345",
"unlocks": "spin_draw",
"customerPhone": "0712345678",
"customerName": "John Doe"
}Customer receives code via email. Gets spin access AND entry into monthly draw. Subtype "R" with receipt tracking.
Staff manually creates order and generates code for customer:
POST /api/business/receipt/generate
{
"amount": 150.00,
"items": [
{ "name": "Pizza", "qty": 1, "price": 120.00 },
{ "name": "Drink", "qty": 1, "price": 30.00 }
],
"cashier": "Mike",
"unlocks": "points",
"customerPhone": "0712345678"
}Staff can read the code to the customer or send it via SMS. Customer earns points and needs another code to access spins. Subtype "R" tracks the transaction.
All codes are generated by the unified business code generator function. The pattern includes plan type and subtype.
| Pattern | Type | Subtype | Example | Points |
|---|---|---|---|---|
| {PREFIX}-{PLAN}{SUBTYPE}-{SEQ}-{RAND} | Receipt | R | BREW-PR-00042-A7X9 | Amount × Business Multiplier |
| {PREFIX}-{PLAN}{SUBTYPE}-{SEQ}-{RAND} | Sticker | S | BREW-PS-00001-B3K2 | Set at batch creation (5-500) |
| {PREFIX}-{PLAN}{SUBTYPE}-{SEQ}-{RAND} | Public Marketing | P | BREW-PP-00015-C7D1 | Business default (points_per_redemption) |
| {PREFIX}-{PLAN}{SUBTYPE}-{SEQ}-{RAND} | QR Code | Q | BREW-PQ-00008-E5F3 | Business default (points_per_redemption) |
Plan Types:S=Starter, P=Pro, E=Enterprise | Subtypes: R=Receipt, S=Sticker, P=Public, Q=QR
| Plan | Requests/min | Requests/day |
|---|---|---|
| Pro | 60 | 5,000 |
| Enterprise | 300 | 50,000 |
We're happy to help your development team get set up — whether you run a POS, e-commerce store, or custom checkout system.