Publisher API

Authentication

Every request requires your API credentials in headers. These are issued by Revifly when your account is approved.

X-API-Key: your_api_key
X-API-Secret: your_api_secret

Credentials are available in your Publisher Portal. Never expose the secret client-side.

Base URL

https://revifly.com/api/v1/publisher/

GET get_offers

Fetch the catalogue of active offers you can promote. Cache this response — it changes infrequently.

Endpoint: GET /api/v1/publisher/get_offers

Query parameters

Response

{
  "status": "success",
  "data": {
    "publisher": { "publisher_id": 1, "publisher_name": "Acme App" },
    "pagination": { "limit": 50, "offset": 0, "count": 12 },
    "offers": [
      {
        "offer_id": 42,
        "brand_id": 7,
        "brand_name": "FashionBrand",
        "title": "20% off your first order",
        "description": "Exclusive discount for new customers.",
        "category": "Fashion",
        "discount_type": "percentage",
        "discount_value": 20.0,
        "min_purchase_amount": 500.0,
        "currency": "INR",
        "start_date": "2026-01-01",
        "end_date": "2026-12-31",
        "status": "active",
        "terms_and_conditions": "Valid on orders of ₹500 or more. Valid until 31 Dec 2026.",
        "image_url": "https://...",
        "brand_logo_url": "https://...",
        "shop_url": "https://fashionbrand.myshopify.com"
      }
    ]
  }
}

GET get_offer_detail impression tracking

Fetch a single offer and record an impression. Call this when you are about to show a specific offer to a specific user — it logs one impression event for brand reporting.

Endpoint: GET /api/v1/publisher/get_offer_detail?offer_id={id}

Query parameters

Response

{
  "status": "success",
  "data": {
    "offer": { /* same fields as get_offers */ }
  }
}

Returns OFFER_NOT_FOUND (404) if the offer is inactive, expired, or not in your catalogue. Rate limit: 200 req/min per publisher.

POST generate_voucher

Generate a unique voucher code for an offer. The voucher is created in Shopify and is ready to use at checkout immediately.

Endpoint: POST /api/v1/publisher/generate_voucher
Content-Type: application/json

Request body

Example request

POST https://revifly.com/api/v1/publisher/generate_voucher
Content-Type: application/json
X-API-Key: your_api_key
X-API-Secret: your_api_secret

{
  "offer_id": 42,
  "customer_identifier": "9b4fc4c2e7c5a2a3e1e9f98b05e3f5b1...",
  "sub_source": "home_feed"
}

Success response

{
  "status": "success",
  "data": {
    "voucher_code": "RV-ABC123XYZ",
    "voucher_id": 456,
    "offer_id": 42,
    "offer_title": "20% off your first order",
    "brand_name": "FashionBrand",
    "expiry": "2026-12-31 23:59:59",
    "image_url": "https://...",
    "checkout_url": "https://fashionbrand.myshopify.com/discount/RV-ABC123XYZ"
  }
}

checkout_url pre-applies the voucher at checkout — link users directly to it to reduce redemption friction.

Active-voucher cap

Each publisher has a configurable cap on how many active (generated but not yet used, unexpired) vouchers a single user can hold simultaneously. The default is 10. If the user is at their cap you will receive:

HTTP 429
{
  "status": "error",
  "message": "User has reached the active voucher limit for this publisher",
  "data": { "error_code": "USER_ACTIVE_VOUCHER_LIMIT" }
}

This is an anti-abuse guard. Contact Revifly support to adjust the cap for your account.

GET user_vouchers wallet API

Fetch all vouchers belonging to a user (identified by their mobile hash) for your publisher account. Use this to build a "My Vouchers" view within your app.

Endpoint: GET /api/v1/publisher/user_vouchers

Query parameters

Response

{
  "status": "success",
  "data": {
    "user_hash": "9b4fc4c2...",
    "pagination": { "limit": 20, "offset": 0, "count": 3 },
    "vouchers": [
      {
        "voucher_id": 456,
        "voucher_code": "RV-ABC123XYZ",
        "offer_id": 42,
        "offer_title": "20% off your first order",
        "brand_name": "FashionBrand",
        "discount_type": "percentage",
        "discount_value": 20.0,
        "currency": "INR",
        "status": "active",
        "validity": "Valid until 31 Dec 2026",
        "expiry_date": "2026-12-31",
        "created_at": "2026-05-18 10:00:00"
      }
    ]
  }
}

Only returns vouchers generated by your publisher account. Rate limit: 100 req/min per publisher.

Hosted wallet page zero build

Instead of building a voucher wallet UI yourself, you can link users to Revifly's hosted wallet page. It shows their available and used vouchers with copy buttons and shop links, served from Revifly's domain.

URL format

https://revifly.com/wallet/?pub={your_publisher_code}&uhash={user_mobile_hash}

Example link

# Compute the user's hash and build the URL
user_hash = mobileHash("919876543210")
wallet_url = "https://revifly.com/wallet/?pub=mypublishercode&uhash=" + user_hash

• No authentication required — the hash itself acts as the key
• The page is noindex — not indexed by search engines
• Shows vouchers for your publisher account only
• Rate limited: 60 requests/min per publisher+hash+IP

Error codes

Integration models

Four ways to distribute Revifly offers — choose based on your platform's capabilities.