Partner API

The Microgenn Loyalty Partner API lets your POS or PMS software award points and redeem coupons for customers enrolled in any loyalty program powered by Microgenn — even if you don't run Microgenn software yourself.

🔍

Look up customer

Get points balance, tier & active coupons by mobile number.

🧾

Post a bill

Award loyalty points when a customer pays their bill.

🎟️

Redeem coupon

Validate and mark a customer's coupon as used.

Base URL: http://loyalty.microgenn.com/api/{tenant-slug}
Replace {tenant-slug} with the loyalty program slug given to you by Microgenn (e.g. spice-garden).

Authentication

Every request must include your API key in the X-API-Key header. Contact the hotel admin to generate a Live key with the read:customers and write:transactions scopes.

HTTP Header

X-API-Key: mg_live_your_key_here

🧪 Sandbox key mg_test_...

Safe for testing. OTP is always 000000. Coupon validation works but nothing is consumed.

🚀 Live key mg_live_...

Production use. Points are awarded, coupons are consumed. Use only when going live.

Sandbox testing

Use a sandbox key (mg_test_...) during development. The API behaves identically to production but:

✓ Customer lookup and bill posting return realistic responses
✓ Coupon validation works (checks expiry, status)
✗ No points are actually awarded or deducted
✗ Coupons are not consumed (status stays active)
✗ No SMS sent for OTP — always returns 000000

Sandbox responses include "sandbox": true so you can tell them apart.

Integration flow

Typical cashier workflow at a partner hotel:

Customer arrives & gives mobile number

Ask the customer for their registered mobile number.

Look up the customer

Call GET /pos/customer?mobile=XXX&create=true to fetch their points balance, tier, and available coupons.

Customer chooses to use a coupon (optional)

Call POST /pos/coupon/redeem with the coupon code to validate & mark it used.

Post the bill

Call POST /pos/bill with the bill amount. Points are awarded automatically.

✓

Show confirmation

Display the new points balance and tier to the customer.

GET

/pos/customer

Look up a customer by mobile number. Returns points balance, tier, and active coupons. Pass create=true to auto-enroll new customers.

Required scope: read:customers

Query Parameters

Param	Required	Description
`mobile`	Yes	10-digit mobile number
`create`	No	Pass `true` to auto-create customer if not found
`name`	No	Customer name (used only when creating)

Request

curl

curl -X GET "http://loyalty.microgenn.com/api/spice-garden/pos/customer?mobile=9876543210&create=true&name=Ravi" \
  -H "X-API-Key: mg_live_your_key_here"

Response — customer found

JSON

{
  "found": true,
  "customer": {
    "customer_id": "uuid...",
    "name": "Ravi Kumar",
    "mobile": "9876543210",
    "points_balance": 3400,
    "segment": "regular"
  },
  "points_balance": 3400,
  "redeemable_value": 34,       // ₹34 discount available
  "redemption_rate": 100,       // 100 pts = ₹1
  "tier": "Gold",
  "priority_service": false,
  "active_coupons": [
    {
      "coupon_id": "uuid...",
      "code": "COUP-XY12",
      "value": 200,           // ₹200 off
      "source": "campaign",
      "expiry_date": "2026-12-31"
    }
  ]
}

Response — not found (without create=true)

{ "found": false, "mobile": "9876543210" }

POST

/pos/bill

Post a customer's bill. Points are calculated automatically based on the loyalty rules and the customer's tier multiplier.

Required scope: write:transactions

Request Body

Field	Required	Description
`mobile`	Yes*	Customer's mobile number (* or customer_id)
`customer_id`	Yes*	Customer UUID (* or mobile)
`amount`	Yes	Bill amount in ₹ (number)
`name`	No	Customer name (used if auto-creating)
`external_ref`	No	Your POS invoice/bill number (for reconciliation)
`items`	No	Array of `{category, name, amount}` for category-based bonus points

Request

curl

curl -X POST "http://loyalty.microgenn.com/api/spice-garden/pos/bill" \
  -H "X-API-Key: mg_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "9876543210",
    "amount": 1500,
    "name": "Ravi Kumar",
    "external_ref": "INV-2026-0042"
  }'

Response

{
  "transaction_id": "uuid...",
  "customer_id": "uuid...",
  "amount": 1500,
  "points_earned": 150000,   // 1500 × 100 base rate
  "points_redeemed": 0,
  "new_balance": 153400,
  "tier": "Gold",
  "tier_upgraded": false,
  "customer": { ... }
}

POST

/pos/coupon/redeem

Validate a coupon code and mark it as used. Call this before posting the bill so the discount is applied first.

Required scope: write:transactions

Request Body

Field	Required	Description
`code`	Yes	The coupon code (e.g. `COUP-XY12`)

Request

curl

curl -X POST "http://loyalty.microgenn.com/api/spice-garden/pos/coupon/redeem" \
  -H "X-API-Key: mg_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"code": "COUP-XY12"}'

Response — valid

{
  "valid": true,
  "value": 200,          // ₹200 discount to apply at billing
  "source": "campaign",
  "coupon": { /* full coupon object */ }
}

Response — invalid / expired

HTTP 400  { "error": "Coupon expired" }
HTTP 400  { "error": "Coupon is used" }
HTTP 404  { "error": "Coupon not found" }

Error codes

HTTP	Meaning	Fix
`401`	Missing or invalid API key	Check your `X-API-Key` header
`403`	API key missing required scope	Ask admin to add `read:customers` / `write:transactions` scope to the key
`400`	Missing required field	Check request body — `mobile` or `amount` likely missing
`404`	Customer / coupon not found	Use `create=true` to auto-create customers; verify coupon code
`500`	Server error	Contact Microgenn support

Need help?

Contact senthil@microgenn.com to get your API key or for integration support.