v1 · Free-to-play promotions only · DPDP Act 2023

Voucher API

Hand out store coupons to your users as free rewards: spin wheels, scratch cards, games and check-ins.

Verified local stores run coupon campaigns on Eligify, for example “₹100 off on bills of ₹500 or more”. Your app shows these campaigns as rewards, and when a user wins you call the Voucher API to issue a coupon. The user walks into the store, shows the coupon, and the store redeems it.

You earn a share of the fee the store pays for each verified walk-in (redemption). Users never pay anything: coupons are free rewards with no cash value, and the games that award them must be free to play.

Every store is verified (KYB) and every campaign is reviewed by Eligify before it goes live, so the offers you show are real and honoured.

Base URL: https://eligify.in/api. All responses are JSON with a top-level `success` flag; errors also carry a machine-readable `code`.

Authentication

Authenticate every request with your partner API key as a Bearer token. Keys are created by Eligify after your agreement and free-to-play declaration are on file. Keep the key on your server; never ship it in a mobile app or browser.

• Authorization

  Bearer elg_pk_<prefix>_<secret>: your partner API key (issued by Eligify, shown once)

• Content-Type

  application/json for POST requests

• Idempotency-Key

  Optional on POST /v1/vouchers: a unique id per reward; retries return the same coupon

// Issue a coupon after a user wins a spin (Node.js, server side)
const res = await fetch('https://eligify.in/api/v1/vouchers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ELIGIFY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `spin_${spinId}`,
  },
  body: JSON.stringify({
    campaignId: 'cmp_9f3a1c2b4d',
    userRef: user.id,
    promotion: { type: 'SPIN_WHEEL', freeToPlay: true },
    customer: { email: user.email, consent: user.savedToEligify },
  }),
});
const { data } = await res.json();
// Show data.code and link the user to data.url (QR code + store addresses)

• Rate limit: 6,000 requests per hour per partner. Exceeding it returns 429 RATE_LIMITED.
• Daily coupon limit: set in your agreement (default 1,000 a day). Exceeding it returns 429 PARTNER_DAILY_LIMIT.
• Send an Idempotency-Key with every issue call so network retries never create a second coupon.
• Campaigns can be for everyone, new customers, returning customers or lapsed customers of that store. Issuing to a user who doesn’t match returns 409 AUDIENCE_MISMATCH; a store that has blocked the user returns 403 CUSTOMER_NOT_ELIGIBLE. Pass `userRef` when listing campaigns to show each user only offers they can win.
• At the store, the customer confirms the coupon is theirs with a one-time code sent to their email. If you shared `customer.email` (with consent), the code goes to that address, so only the winner can redeem it; a shared `customer.phone` must also match if the cashier enters one.
• Issue at scale with POST /v1/vouchers/batch: up to 100 coupons per call, each with its own idempotencyKey. Results come back per item (HTTP 207 if some failed); retrying the batch is safe.
• Keys are scoped: ask Eligify for a key per server, with only the permissions it needs (vouchers:read, vouchers:issue, wallet:read, giftcards:order…). Calls without the right scope return 403 MISSING_SCOPE.
• Signed keys: every request must send X-Eligify-Timestamp (unix seconds) and X-Eligify-Signature: v1=<hex HMAC-SHA256(signingSecret, "<timestamp>.<METHOD>.<path?query>.<raw body>")>. Requests older than 5 minutes or replayed are refused.
• Gift Card API (giftcards:* scopes): GET /v1/giftcards/catalog?category=&tag=&q=, POST /v1/giftcards/orders (Idempotency-Key required; paid from your prepaid balance), GET /v1/giftcards/orders/{orderId}?reveal=1.
• Campaigns may cap coupons handed out per day: once reached, issuing returns 409 CAMPAIGN_DAILY_LIMIT until midnight IST.
• If Eligify has your server IPs on an allow list, requests from other IPs are refused with 403 IP_NOT_ALLOWED.

List live campaigns

Campaigns you may hand out right now, ordered by end date. Filter by `city`, `pincode` or `category` (FOOD, CAFE, GROCERY, FASHION, BEAUTY, ELECTRONICS, HOME, HEALTH, FITNESS, ENTERTAINMENT, SERVICES, OTHER). Only stores with at least one open location are returned; up to 100 campaigns. Pass `userRef` to leave out campaigns that user can’t win (offers for new or returning customers depend on their history with each store). `terms` is the full list to show before the user plays: it is generated from the campaign’s rules (audience, redemption days and hours, what it covers) followed by the store’s own terms.

GET /api/v1/vouchers/campaigns?city=Bengaluru&category=CAFE&userRef=user_48213

{
  "success": true,
  "data": [
    {
      "campaignId": "cmp_9f3a1c2b4d",
      "title": "Weekend coffee treat",
      "store": "Brew Street Cafe",
      "category": "CAFE",
      "offer": "₹100 off on bills of ₹500 or more",
      "offerType": "FLAT",
      "value": 100,
      "minBillAmount": 500,
      "terms": [
        "For first-time customers only.",
        "Redeem Saturdays and Sundays, 8 am to 12 pm.",
        "Cannot be combined with other offers.",
        "One coupon per customer."
      ],
      "audience": "NEW",
      "highlights": [
        "Freshly roasted single-origin beans"
      ],
      "howToRedeem": "Show the QR at the billing counter before you order.",
      "startsAt": "2026-10-01T00:00:00.000Z",
      "endsAt": "2026-10-31T18:29:59.000Z",
      "couponValidityDays": 14,
      "remaining": 412,
      "perUserLimit": 1,
      "locations": [
        {
          "id": "loc_1a2b3c4d5e",
          "name": "Indiranagar",
          "city": "Bengaluru",
          "pincode": "560038",
          "address": "12, 100 Feet Rd, Bengaluru"
        }
      ]
    }
  ]
}

Issue a coupon

Gives one coupon from a live campaign to one of your users. Call it only after the user wins a free promotion. The response includes the code and a coupon page URL with a QR code and the store addresses; show both to the user.

{
  "campaignId": "cmp_9f3a1c2b4d",
  "userRef": "user_48213",
  "promotion": {
    "type": "SPIN_WHEEL",
    "freeToPlay": true
  },
  "customer": {
    "email": "asha@example.com",
    "consent": true
  }
}

{
  "success": true,
  "data": {
    "code": "K7QM-4XPA",
    "status": "ACTIVE",
    "url": "https://eligify.in/c/K7QM-4XPA",
    "campaignId": "cmp_9f3a1c2b4d",
    "store": "Brew Street Cafe",
    "title": "Weekend coffee treat",
    "offer": "₹100 off on bills of ₹500 or more",
    "minBillAmount": 500,
    "terms": [
      "Valid once per customer."
    ],
    "issuedAt": "2026-10-12T10:15:00.000Z",
    "expiresAt": "2026-10-26T10:15:00.000Z",
    "userRef": "user_48213",
    "locations": [
      {
        "id": "loc_1a2b3c4d5e",
        "name": "Indiranagar",
        "address": "12, 100 Feet Rd, Bengaluru, 560038",
        "city": "Bengaluru"
      }
    ]
  }
}

Get a coupon

Status of a coupon you issued: ACTIVE, REDEEMED, EXPIRED or VOID. Coupons issued by other partners return 404.

GET /api/v1/vouchers/K7QM-4XPA

{
  "success": true,
  "data": {
    "code": "K7QM-4XPA",
    "status": "REDEEMED",
    "redeemedAt": "2026-10-14T13:02:11.000Z",
    "store": "Brew Street Cafe"
  }
}

Good practice

Compliance

• Free-to-play only

  Under the Promotion and Regulation of Online Gaming Act, 2025, money games are prohibited. Coupons may only reward free promotions. API calls must set promotion.freeToPlay = true; partners found charging users are blocked.

• No cash value

  Coupons are store-funded discounts, usable once at the issuing store. They hold no stored value and cannot be exchanged for money, so they are not prepaid payment instruments.

• Consent (DPDP Act, 2023)

  Email or phone may be shared only when the user agrees to save the coupon to Eligify. Without consent, Eligify only receives your opaque userRef.

• Reviewed offers

  Every store completes KYB and every campaign is approved by Eligify before it appears in GET /v1/vouchers/campaigns.