Loyalty (Public API)

The public loyalty API allows your applications to interact with the loyalty program on behalf of customers. Use it to check point balances, award points from external systems, redeem rewards, browse the rewards catalog, and verify voucher codes.

All public API endpoints require an API key passed via the X-Api-Key header. You can generate API keys from the Umbra ERP dashboard under Settings > API Keys.

GET/v1/public/loyalty/balance

Check balance

Check a customer's current loyalty point balance and tier information.

Required parameters

Name
email
Type
string
Description
The customer's email address to look up their loyalty membership.

Requires API key via X-Api-Key header.

Request

GET

/v1/public/loyalty/balance

curl "https://api.umbraerp.com/v1/public/loyalty/balance?email=john@example.com" \
  -H "X-Api-Key: <your_api_key>"

Response

{
  "result": "success",
  "data": {
    "customerName": "John Moyo",
    "tierName": "Gold",
    "tierColor": "#FFD700",
    "pointsBalance": 2400,
    "lifetimePoints": 8200,
    "pointsName": "Stars"
  }
}

POST/v1/public/loyalty/earn

Earn points

Award points to a customer from an external system, such as a POS integration or e-commerce platform.

Required attributes

Name
email
Type
string
Description
The customer's email address.
Name
amount
Type
number
Description
The transaction amount in the program's currency. Points will be calculated using the program's pointsPerCurrency ratio.

Optional attributes

Name
reference
Type
string
Description
External reference ID for the transaction (e.g., order number).
Name
description
Type
string
Description
Description of how points were earned.

Requires API key via X-Api-Key header.

Request

POST

/v1/public/loyalty/earn

curl -X POST https://api.umbraerp.com/v1/public/loyalty/earn \
  -H "X-Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "amount": 150.00,
    "reference": "ORD-2026-0042",
    "description": "Online purchase"
  }'

Response

{
  "result": "success",
  "data": {
    "pointsEarned": 1500,
    "multiplierApplied": 1.5,
    "newBalance": 3900,
    "tierName": "Gold"
  }
}

POST/v1/public/loyalty/redeem

Redeem reward

Redeem a reward for a customer. The customer's point balance will be debited by the reward's point cost, and a voucher code will be generated.

Required attributes

Name
email
Type
string
Description
The customer's email address.
Name
rewardId
Type
string
Description
Public ID of the reward to redeem.

Requires API key via X-Api-Key header.

Request

POST

/v1/public/loyalty/redeem

curl -X POST https://api.umbraerp.com/v1/public/loyalty/redeem \
  -H "X-Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "rewardId": "rwd-002"
  }'

Response

{
  "result": "success",
  "data": {
    "redemptionId": "rdm-003",
    "rewardName": "10% Discount Voucher",
    "pointsSpent": 200,
    "newBalance": 3700,
    "voucherCode": "VOUCH-G7H8I9",
    "expiresAt": "2026-04-17T15:30:00Z"
  }
}

GET/v1/public/loyalty/rewards

Get rewards catalog

Retrieve the list of active rewards available for redemption. Use this to display the rewards catalog in your customer-facing application.

Requires API key via X-Api-Key header.

Request

GET

/v1/public/loyalty/rewards

curl https://api.umbraerp.com/v1/public/loyalty/rewards \
  -H "X-Api-Key: <your_api_key>"

Response

{
  "result": "success",
  "data": [
    {
      "publicId": "rwd-001",
      "name": "Free Oil Change",
      "description": "Complimentary oil change service",
      "pointsCost": 500,
      "rewardType": "service"
    },
    {
      "publicId": "rwd-002",
      "name": "10% Discount Voucher",
      "description": "10% off your next purchase",
      "pointsCost": 200,
      "rewardType": "discount",
      "discountPercent": 10
    }
  ]
}

GET/v1/public/loyalty/vouchers/:code/verify

Verify voucher code

Verify whether a voucher code is valid. Use this at checkout or point-of-sale to validate customer vouchers before applying discounts or fulfilling rewards.

Requires API key via X-Api-Key header.

Request

GET

/v1/public/loyalty/vouchers/VOUCH-A1B2C3/verify

curl https://api.umbraerp.com/v1/public/loyalty/vouchers/VOUCH-A1B2C3/verify \
  -H "X-Api-Key: <your_api_key>"

Response

{
  "result": "success",
  "data": {
    "valid": true,
    "voucherCode": "VOUCH-A1B2C3",
    "rewardName": "Free Oil Change",
    "rewardType": "service",
    "status": "pending",
    "redeemedAt": "2026-03-15T11:00:00Z",
    "expiresAt": "2026-04-15T11:00:00Z"
  }
}