Partner API Documentation

1. Overview & Architecture

The Elite Club Partner API is a dedicated, white-label integration layer built exclusively for the Bank. It is not a public or general-purpose API, and it is not versioned or marketed alongside Elite Club's consumer-facing products. Its sole purpose is to let the Bank backend retrieve Elite Club offers and present them inside the Bank's own mobile application, under the Bank's own branding.

1.1 Request Flow

1.2 Responsibilities

2. Base URL

All endpoints documented here are relative to this base URL, under the versioned path /partner/v1. For example, the offers listing endpoint is reachable at https://appapi.eliteclub.global/partner/v1/offers/exclusive.

3. Authentication

The Partner API uses the OAuth 2.0 Client Credentials grant. This is a machine-to-machine flow — there is no end-user login or redirect step. The Bank backend authenticates as itself, then identifies individual customers separately via partner_user_id on each business request.

3.1 Request an Access Token

{
  "client_id": "bankx-prod-client",
  "client_secret": "••••••••••••••••••••••••••••",
  "grant_type": "client_credentials"
}

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 604800
}

3.2 Using the Access Token

Every protected endpoint requires the token on every request:

3.3 Token Lifetime & Renewal

• Access tokens are valid for 604800 seconds (1 week), reflected in expires_in.
• There is no refresh token. When a token expires, request a new one from /partner/v1/oauth/token using the same client credentials.
• The Bank backend should cache the token in memory or a shared cache and request a new one proactively — for example, 5 minutes before expires_in elapses — rather than on every request.
• Requests made with an expired or invalid token receive 401 Unauthorized.

3.4 Transport Security

3.5 IP Whitelisting

Each client_id is bound to a set of allowlisted source IP addresses or CIDR ranges, configured during onboarding. Requests originating from a non-allowlisted IP are rejected with 403 Forbidden, even if the credentials are otherwise valid. IP ranges are managed per environment (UAT and production are independent).

3.6 Authentication Errors

4. Common Headers

5. Common Response Format

Every endpoint returns a single, consistent envelope, regardless of success or failure.

5.1 Success Envelope

{
  "success": true,
  "message": "Request processed successfully.",
  "data": {},
  "meta": {}
}

5.2 Error Envelope

{
  "success": false,
  "message": "Human-readable description of the error.",
  "data": null,
  "meta": {
    "error_code": "VALIDATION_ERROR",
    "correlation_id": "c3f6a8e2-4a41-4e2a-9d10-2f5b6b6a9b10"
  }
}

6. Pagination & Filtering

6.1 Pagination Parameters

6.2 Pagination Meta

"meta": {
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_pages": 8,
    "total_records": 152
  },
  "correlation_id": "c3f6a8e2-4a41-4e2a-9d10-2f5b6b6a9b10",
  "generated_at": "2026-07-15T10:32:00Z"
}

6.3 Filtering

Listing endpoints accept multi-select country and category filters, plus a free-text search parameter and a latest filter. country and category are integer identifiers and support multiple values in a single request (for example country=12,18 and category=1,5) — do not hardcode them. Each listing response includes the full, current set of valid countries and categories for the Bank to render as filter options and to pass back on subsequent calls. When latest=1 is supplied, only offers created in the last 90 days are returned.

7. User Identification

The OAuth2 access token identifies the Bank as the calling system. It does not identify an individual customer. Each business request additionally carries:

• partner_user_id is generated and owned by the Bank — it can be an account number, a hashed customer id, or any stable identifier chosen by the Bank.
• Elite Club internally maps partner_user_id to its own member record. This mapping is transparent to the Bank.
• The Bank never needs to know, store, or handle Elite Club's internal member identifiers.
• partner_user_id should remain stable for the lifetime of the customer relationship; changing it will be treated as a different customer.

8. Common Request Parameters

Every business (non-authentication) endpoint accepts the following parameters:

9. Endpoint Summary

Bootstrap

Offers (Bearer Token Required)

10. Endpoint Details

GET /partner/v1/offers/exclusive?partner_user_id=BANKX-88213&country=12,18&category=1,5&latest=1&page=1&limit=20 HTTP/1.1
Host: appapi.eliteclub.global
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

{
  "success": true,
  "message": "Offers retrieved successfully.",
  "data": {
    "countries": [
      { "id": 12, "name": "United Arab Emirates" },
      { "id": 18, "name": "Saudi Arabia" }
    ],
    "categories": [
      { "id": 1, "name": "Restaurants & Cafes" },
      { "id": 2, "name": "Fitness & Wellness" },
      { "id": 3, "name": "Other Services" },
      { "id": 4, "name": "Lifestyle & Activities" },
      { "id": 5, "name": "Hotels & Resorts" },
      { "id": 6, "name": "Beach Clubs" }
    ],
    "offers": [
      {
        "offer_id": 10432,
        "title": "50% Off Any Main Course",
        "name": "Business Bay Grill – Chef's Choice",
        "description": "Enjoy 50% off any single main course at Business Bay Grill, Dubai.",
        "category": { "id": 1, "name": "Restaurants & Cafes", "icon_url": "https://ecsystem.eliteclub.global/uploads/icons/restaurants-cafes.png" },
        "country": { "id": 12, "name": "United Arab Emirates" },
        "offer_type": "discount",
        "discount": {
          "type": "percentage",
          "percentage": 50,
          "fixed_amount": null,
          "currency": "AED"
        },
        "estimated_saving": { "amount": 45.00, "currency": "AED" },
        "best_seller": true,
        "merchant": {
          "type": "outlet",
          "id": 552,
          "name": "Business Bay Grill",
          "address": "Bay Avenue, Business Bay, Dubai, UAE",
          "latitude": 25.1857,
          "longitude": 55.2631
          ,"currency": "AED"
        },
        "image_url": "https://ecsystem.eliteclub.global/uploads/files/Business%20Bay%20Grill-cover().jpg",
        "distance_km": 3.42
      }
    ]
  },
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total_pages": 8,
      "total_records": 152
    },
    "correlation_id": "c3f6a8e2-4a41-4e2a-9d10-2f5b6b6a9b10",
    "generated_at": "2026-07-15T10:32:00Z"
  }
}

GET /partner/v1/offers/premium?partner_user_id=BANKX-88213&page=1&limit=20 HTTP/1.1
Host: appapi.eliteclub.global
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

GET /partner/v1/offers/10432?partner_user_id=BANKX-88213&latitude=25.2048&longitude=55.2708 HTTP/1.1
Host: appapi.eliteclub.global
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

{
  "success": true,
  "message": "Offer retrieved successfully.",
  "data": {
    "offer_id": 10432,
    "title": "50% Off Any Main Course",
    "name": "Business Bay Grill – Chef's Choice",
    "description": "Enjoy 50% off any single main course at Business Bay Grill, Dubai.",
    "category": { "id": 1, "name": "Restaurants & Cafes", "icon_url": "https://ecsystem.eliteclub.global/uploads/icons/restaurants-cafes.png" },
    "country": { "id": 12, "name": "United Arab Emirates" },
    "offer_type": "discount",
    "discount": {
      "type": "percentage",
      "percentage": 50,
      "fixed_amount": null,
      "currency": "AED"
    },
    "estimated_saving": { "amount": 45.00, "currency": "AED" },
    "validity": {
      "duration_type": "limited",
      "from_date": "2026-01-01",
      "to_date": "2026-12-31",
      "valid_any_day": false,
      "available_days": [
        { "day": "Mon", "from": "12:00", "to": "23:00" },
        { "day": "Tue", "from": "12:00", "to": "23:00" },
        { "day": "Wed", "from": "12:00", "to": "23:00" }
      ]
    },
    "redemption_limits": {
      "quantity_per_customer_type": "quantity",
      "quantity_per_customer": 2,
      "quantity_per_visit": 1,
      "redeemed_count_for_customer": 0
    },
    "best_seller": true,
    "merchant": {
      "type": "outlet",
      "id": 552,
      "name": "Business Bay Grill",
      "address": "Bay Avenue, Business Bay, Dubai, UAE",
      "latitude": 25.1857,
      "longitude": 55.2631,
      "currency": "AED"
    },
    "image_url": "https://ecsystem.eliteclub.global/uploads/files/Business%20Bay%20Grill-cover().jpg",
    "kids_policy": "",
    "kids_policy_ar": "",
    "terms": [
      "One redemption per visit.",
      "Not valid in conjunction with other offers or promotions."
    ],
    "distance_km": 3.42
  },
  "meta": {
    "correlation_id": "7bd80858-1e17-45be-a307-f5412fb66831",
    "generated_at": "2026-07-15T10:32:00Z"
  }
}

POST /partner/v1/offers/redeem HTTP/1.1
Host: appapi.eliteclub.global
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "partner_user_id": "BANKX-88213",
  "offer_id": 10432,
  "pincode": "4821",
  "quantity": 1,
  "outlet_id": 552,
  "paid_amount": 90.00,
  "check_number": "A1001",
  "guests_number": 2,
  "currency": "AED"
}

POST /partner/v1/offers/redeem HTTP/1.1
Host: appapi.eliteclub.global
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "partner_user_id": "BANKX-88213",
  "offer_id": 20115,
  "pincode": "7734",
  "quantity": 1,
  "hotel_id": 88
}

{
  "success": true,
  "message": "Offer redeemed successfully.",
  "data": {
    "authcode": "EC-D-98341",
    "redeemed_at": "2026-07-15T13:42:00Z"
  },
  "meta": {
    "correlation_id": "2de939fd-25a0-4f89-b336-e2f8b1d8c2de"
  }
}

11. The Offer Object — Field Dictionary

The Detail column indicates whether a field is present in the summarized listing object, the full detail object, or both.

12. HTTP Status Codes

13. Error Codes

Error Response Examples

401 — invalid_token

{
  "success": false,
  "message": "Access token is invalid or has expired.",
  "data": null,
  "meta": {
    "error_code": "invalid_token",
    "correlation_id": "f2a84f84-7d31-49ef-9328-f266e9d4dc62"
  }
}

404 — resource_not_found

{
  "success": false,
  "message": "The requested offer could not be found.",
  "data": null,
  "meta": {
    "error_code": "resource_not_found",
    "correlation_id": "9170f7bb-35d8-4768-b2cc-0d73fa8f4a97"
  }
}

422 — validation_error

{
  "success": false,
  "message": "Validation failed.",
  "data": null,
  "meta": {
    "error_code": "validation_error",
    "errors": {
      "partner_user_id": ["The partner_user_id field is required."],
      "limit": ["The limit must not be greater than 50."]
    },
    "correlation_id": "7bd80858-1e17-45be-a307-f5412fb66831"
  }
}

409 — insufficient_quantity

{
  "success": false,
  "message": "This offer has no remaining quantity available.",
  "data": null,
  "meta": {
    "error_code": "insufficient_quantity",
    "correlation_id": "3af1c9a0-6b0e-4e39-9a2a-1f9d2e6b7c44"
  }
}

409 — redemption_limit_exceeded

{
  "success": false,
  "message": "This customer has reached the maximum allowed redemptions for this offer.",
  "data": null,
  "meta": {
    "error_code": "redemption_limit_exceeded",
    "remaining_quantity": 0,
    "correlation_id": "8e2b9f11-2c34-4a4e-8b39-5a6f0c2d9e77"
  }
}

14. Security

• OAuth 2.0 Client Credentials — the sole authentication mechanism; no end-user credentials are ever handled by Elite Club.
• HTTPS everywhere — every environment enforces TLS; plain HTTP is rejected.
• TLS 1.2+ — minimum supported protocol version, with modern cipher suites only.
• IP Whitelisting — each client_id is restricted to pre-approved source IP ranges.
• Short-lived access tokens — 1-week expiry, no long-lived or refresh tokens, limiting the blast radius of a leaked token.
• Audit logging — every request is logged with client_id, endpoint, timestamp, and correlation_id for traceability and incident investigation.
• Correlation IDs — the Bank should generate and send X-Correlation-Id on every request so that a single customer action can be traced across both systems.
• Redemption audit trail — every call to /partner/v1/offers/redeem is logged with authcode, partner_user_id, and correlation_id for financial reconciliation and dispute investigation.
• Versioning — the API is explicitly versioned in the URL (/partner/v1), so future breaking changes never silently affect existing integrations.

15. Versioning Policy

• Current version: /partner/v1.
• Backwards-compatible additions (new optional fields, new endpoints) may be introduced without a version bump.
• Breaking changes are released under a new path, e.g. /partner/v2, with advance notice to the Bank.
• Deprecated versions remain available for an agreed transition period before retirement.

16. Best Practices

• Cache access tokens for their full lifetime; do not request a new token on every API call.
• Generate a fresh X-Correlation-Id per request and log it alongside your own request identifiers.
• Read country and category filter values from the discovery lists in the listing responses — do not hardcode ids; both filters support multi-select values in a single request.
• Use latest=1 when the Bank app needs a "latest offers" view limited to offers created in the last 90 days.
• Treat partner_user_id as an opaque, stable identifier; do not reuse it across different customers.
• Always branch on the success field in the response body, not solely on HTTP status.
• Fetch full offer details lazily (only when a customer opens an offer), and use the listing endpoints for browsing.
• Only call /partner/v1/offers/redeem once merchant staff has entered the redemption pincode at checkout — never pre-emptively, and never source it from the app user.
• Send only the fields relevant to the offer's offer_type on redemption — omit paid_amount, check_number, guests_number, and currency for BOGOF offers.

17. Integration Checklist

18. Sandbox Environment

A self-contained sandbox is available so the Bank's engineering team can build and test their integration end-to-end before real credentials, real merchant data, or a production go-live date are in place. The sandbox implements the exact same request and response contract documented above, but every response is static mock data — no request ever touches real Elite Club members, merchants, or redemption records.

18.1 Sandbox Endpoints

18.2 Discovery Lists

The sandbox exposes two discovery endpoints so the Bank can populate filter menus without relying on the offer listing responses:

• GET /partner-sandbox/v1/offers/countries returns the fixed country list used by the sandbox offer catalog.
• GET /partner-sandbox/v1/offers/categories returns the fixed category list used by the sandbox offer catalog.
• Both endpoints return the standard response envelope with success: true, a short status message, data as an array of { id, name } objects, and meta: null.

18.3 Simplified Authentication

• POST /partner-sandbox/v1/oauth/token accepts any client_id / client_secret value, as long as grant_type is client_credentials and all three fields are present — it always returns the same mock access_token, valid for the standard expires_in of 604800 seconds.
• Every other sandbox endpoint only checks that an Authorization: Bearer <token> header is present — any non-empty token is accepted. Omitting the header returns the same 401 invalid_token shape as production, so error handling can still be tested.
• There is no IP allowlist on the sandbox.

18.4 Fixed Offer Catalog

The sandbox always serves the same four offers, split across tiers, so responses are predictable while you build against them.

Any other offer_id returns 404 offer_not_found, exactly as production would for an unknown or inactive offer.

18.5 Deterministic Test Triggers for Redeem

Use these reserved input values against POST /partner-sandbox/v1/offers/redeem to deliberately exercise each error path documented in Redeem Offer, without needing to reverse-engineer real business conditions.