For Developers

API Reference

Integrate Engage with your POS system. Generate receipt codes, validate codes, and manage your business programmatically.

Authentication

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.

What Engage Needs From Your POS

Engage does not record your receipts or store your sales data. We only need the cart total to calculate appropriate points. The items array is optional and only used for your own records if you choose to include it.

We Need

• Cart total (amount)
• That's it

We Don't Need

• Full receipt data
• Customer payment details
• Inventory information
• Your sales history

Points Calculation: Points = Cart Amount × Your Business Multiplier

Example: Cart total = KES 250, Multiplier = 2.0 → Customer gets 500 points

Endpoints

POST/api/business/receipt/generateAPI KeyPro & Enterprise

Generate Receipt Code

Generate a unique code for a customer receipt. The code will have pre-calculated points based on your business multiplier and the cart total.

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 name
}

Response

{
  "success": true,
  "receipt": {
    "receipt_id": "uuid",
    "receipt_number": "RCPT-0042",
    "code": "BREW-R-260714-A7X9",
    "points_earned": 500,
    "amount": 250.00,
    "business_name": "Brew & Bean Coffee",
    "business_slug": "brew-bean",
    "qr_url": "/spin?code=BREW-R-260714-A7X9"
  }
}

Notes

• Points are calculated as: amount × your business multiplier
• Each code is single-use and unique
• The code activates the customer for 30 days
• Codes follow the pattern: {PREFIX}-R-{DATE}-{RANDOM}

GET/api/code/lookupNone (public)All Plans

Look Up Code

Validate a code and get its details. Useful for checking if a code is still valid before printing.

Request

GET /api/code/lookup?code=BREW-R-260714-A7X9

Response

{
  "success": true,
  "code": "BREW-R-260714-A7X9",
  "unlocks": "spin",
  "business_id": "uuid",
  "business_name": "Brew & Bean Coffee",
  "business_slug": "brew-bean",
  "business_logo": "https://...",
  "business_color": "#8B5CF6",
  "redirect_url": "/brew-bean/spin"
}

Notes

• No authentication required
• Returns 404 if code is invalid or expired
• Use this to pre-validate codes before printing

Code Patterns

Pattern	Type	Example	Points
{PREFIX}-S-{SEQ}-{RAND}	Sticker	BREW-S-0001-A7X9	Set at batch creation (5-500)
{PREFIX}-R-{DATE}-{RAND}	Receipt (POS)	BREW-R-260714-B3K2	Amount × Business Multiplier
{PREFIX}-PUB-{LABEL}	Public Marketing	BREW-PUB-WEEKEND	Business default (points_per_redemption)
{PREFIX}-QR-{SEQ}	QR Code	BREW-QR-0001	Business default (points_per_redemption)

Rate Limits

Plan	Requests/min	Requests/day
Pro	60	5,000
Enterprise	300	50,000

Need help integrating?

We're happy to help your development team get set up.

Contact Developer Support

Authentication

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.

What Engage Needs From Your POS

We Need

• Cart total (amount)
• That's it

We Don't Need

• Full receipt data
• Customer payment details
• Inventory information
• Your sales history

Points Calculation: Points = Cart Amount × Your Business Multiplier

Example: Cart total = KES 250, Multiplier = 2.0 → Customer gets 500 points

Endpoints

POST/api/business/receipt/generateAPI KeyPro & Enterprise

Generate Receipt Code

Generate a unique code for a customer receipt. The code will have pre-calculated points based on your business multiplier and the cart total.

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 name
}

Response

{
  "success": true,
  "receipt": {
    "receipt_id": "uuid",
    "receipt_number": "RCPT-0042",
    "code": "BREW-R-260714-A7X9",
    "points_earned": 500,
    "amount": 250.00,
    "business_name": "Brew & Bean Coffee",
    "business_slug": "brew-bean",
    "qr_url": "/spin?code=BREW-R-260714-A7X9"
  }
}

Notes

• Points are calculated as: amount × your business multiplier
• Each code is single-use and unique
• The code activates the customer for 30 days
• Codes follow the pattern: {PREFIX}-R-{DATE}-{RANDOM}

GET/api/code/lookupNone (public)All Plans

Look Up Code

Validate a code and get its details. Useful for checking if a code is still valid before printing.

Request

GET /api/code/lookup?code=BREW-R-260714-A7X9

Response

{
  "success": true,
  "code": "BREW-R-260714-A7X9",
  "unlocks": "spin",
  "business_id": "uuid",
  "business_name": "Brew & Bean Coffee",
  "business_slug": "brew-bean",
  "business_logo": "https://...",
  "business_color": "#8B5CF6",
  "redirect_url": "/brew-bean/spin"
}

Notes

• No authentication required
• Returns 404 if code is invalid or expired
• Use this to pre-validate codes before printing

Code Patterns

Pattern	Type	Example	Points
{PREFIX}-S-{SEQ}-{RAND}	Sticker	BREW-S-0001-A7X9	Set at batch creation (5-500)
{PREFIX}-R-{DATE}-{RAND}	Receipt (POS)	BREW-R-260714-B3K2	Amount × Business Multiplier
{PREFIX}-PUB-{LABEL}	Public Marketing	BREW-PUB-WEEKEND	Business default (points_per_redemption)
{PREFIX}-QR-{SEQ}	QR Code	BREW-QR-0001	Business default (points_per_redemption)

Plan

Requests/min

Requests/day

Pro

5,000

Enterprise

300

50,000