Apply Coupons API V1 – Developer Documentation

Authentication

Use HTTP Basic Authentication. Send partner email as username and account password as password. Example header:

Authorization: Basic base64(username:password)

Standard Response Format

{
  "success": true|false,
  "data": {...} | [],
  "message": "Human readable message"
}

Endpoints

1. Get Product Categories

GET /categories

Logic

Returns all categories allowed for the authenticated partner.

Request Example

GET /categories

Sample Response

{
  "success": true,
  "data": [
    {"id":54,"title":"Brawl Stars"},
    {"id":55,"title":"Clash of Clans"}
  ],
  "message": "Product Categories retrieved successfully."
}

cURL

curl -u username:password https://api.apply.coupons/v1/categories

Typical Errors

404 – No categories found

{
  "success": false,
  "message": "Product Categories not found."
}

2. Get Products

GET /products?category_id=54

Validation Rules

category_id: optional integer

Logic

Fetches all products or products filtered by category_id.

Request Example

GET /products?category_id=54

Sample Response

{
  "success": true,
  "data": [
    {"id":35,"name":"Brawl Stars - 30 💎","price":"1.78"},
    {"id":36,"name":"Brawl Stars - 80 💎","price":"4.45"}
  ],
  "message": "Products retrieved successfully."
}

cURL

curl -u username:password "https://api.apply.coupons/v1/products?category_id=54"

Typical Errors

404 – No products found in the category

{
  "success": false,
  "message": "Products not found."
}

3. Get Transactions

GET /transactions?per_page=20&page=1

Validation Rules

per_page: optional integer (default 20)
page: optional integer (default 1)

Logic

Returns paginated purchase transactions for the authenticated partner.

Request Example

GET /transactions?per_page=20&page=1

Sample Response

{
  "success": true,
  "data": {
    "current_page":1,
    "data":[
      {
        "id":"XXXX-XXXX-XXXX",
        "product_name":"Product Clash of Clans - 80 💎",
        "amount":"0.89 USD",
        "quantity":100,
        "total_amount":"89.00 USD",
        "created_at":"2025-09-28 08:53:57 UTC"
      }
    ],
    "total":158
  },
  "message":"Transactions retrieved successfully."
}

cURL

curl -u username:password "https://api.apply.coupons/v1/transactions?per_page=20&page=1"

Typical Errors

Empty page returns HTTP 200 with data: [].

4. Get One Transaction

GET /transactions/{id}

Validation Rules

id: required UUID of an existing transaction

Logic

Returns details of a single transaction including decrypted voucher codes.

Request Example

GET /transactions/XXXX-XXXX-XXXX

Sample Response

{
  "success": true,
  "data": {
    "id":"XXXX-XXXX-XXXX",
    "product_name":"Product Brawl Stars - 30 💎",
    "amount":"1.78 USD",
    "quantity":1,
    "total_amount":"1.78 USD",
    "voucher_codes":["XXXX-XXXX-XXXX"],
    "created_at":"2025-09-27 17:12:01 UTC"
  },
  "message":"Transaction retrieved successfully."
}

cURL

curl -u username:password https://api.apply.coupons/v1/transactions/XXXX-XXXX-XXXX

Typical Errors

404 – Transaction not found

{
  "success": false,
  "message": "Transaction not found."
}

5. Check Balance

GET /check-balance

Logic

Returns partner’s current wallet balance and currency symbol.

Request Example

GET /check-balance

Sample Response

{
  "success": true,
  "data": { "balance": 0.41, "currency": "USD" },
  "message": "User balance retrieved successfully."
}

cURL

curl -u username:password https://api.apply.coupons/v1/check-balance

6. Check Voucher

POST /check-voucher

Validation Rules

voucher_code: required string

Logic

Verifies voucher validity and redemption status. RateLimiter: **max 5 attempts per 5 minutes**.

Request Example

POST /check-voucher
{
  "voucher_code":"XXXX-XXXX-XXXX"
}

Sample Response

{
  "success": true,
  "data": {
    "is_redeemed": true,
    "order_number": 113450,
    "customer_email": "[email protected]",
    "product_name": "Brawl Stars - Brawl Pass Plus",
    "order_status": "completed",
    "redeemed_at": "2025-09-27 12:07:32 UTC"
  },
  "message": "Voucher retrieved successfully."
}

cURL

curl -u username:password -X POST https://api.apply.coupons/v1/check-voucher \
  -H "Content-Type: application/json" \
  -d '{"voucher_code":"XXXX-XXXX-XXXX"}'

Typical Errors

422 – Missing voucher_code

{
  "success": false,
  "message": "Validation Error.",
  "data": { "voucher_code": ["The voucher code field is required."] }
}

404 – Voucher not found

{
  "success": false,
  "message": "Voucher not found."
}

429 – Too many attempts (rate limited)

{
  "success": false,
  "message": "You have been blocked by the system for logging in more than 5 times. Please try again after 300 seconds"
}

7. Create Voucher

POST /create-voucher

Validation Rules

product_id: required integer, must exist
quantity: required integer, min 1, max 100

Logic

Verifies product belongs to allowed categories.
Calculates total price and checks partner balance.
Creates a PartnerTransaction with UUID.
Generates secure voucher codes.
Dispatches CustomerBalanceChangeEvent to update balance.

Request Example

POST /create-voucher
{
  "product_id": 42,
  "quantity": 1
}

Sample Response

{
  "success": true,
  "data": {
    "product_name": "Clash of Clans - 80 💎",
    "transaction_id": "XXXX-XXXX-XXXX",
    "voucher_codes": ["XXXX-XXXX-XXXX"]
  },
  "message": "Voucher created successfully."
}

cURL

curl -u username:password -X POST https://api.apply.coupons/v1/create-voucher \
  -H "Content-Type: application/json" \
  -d '{"product_id":42,"quantity":1}'

Typical Errors

402 – Insufficient Balance

{ "success": false, "message": "Please top up your balance by 10.00 USD." }

404 – Product Not Found

{ "success": false, "message": "Product Not Found" }

404 – Partner Not Found (invalid partner status)

{ "success": false, "message": "Partner Not Found" }