Apply Coupons Supercell API V1 – Developer Documentation

Latest Updates

January 25, 2026

New Get Orders Endpoint Added

New /v1/orders endpoint now available! Retrieve paginated orders with optional status filtering. Supports new, processing, completed, canceled, and sign_in_verified status filters.

January 25, 2026

New Cancel Order Endpoint Added

New /v1/cancel-order endpoint allows partners to cancel orders that are still in "processing" status before OTP submission.

January 20, 2026

Update Documentation Improvements

Added collapsible sections, copy buttons for code snippets, and improved overall documentation styling for better developer experience.

IP White LIST

▼

Your IP (x.x.x.x) has not access

Information: For this you must send your server reserved IP to our team. Please provide your server's IP address so we can add it to our whitelist and grant you access.

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 /v1/categories

▼

Logic

Returns all categories allowed for the authenticated partner, including required fields for ordering.

Request Example

GET /v1/categories

Sample Response

{
  "success": true,
  "data": [
    {
      "id": 54,
      "title": "Brawl Stars",
      "fields": [
        {
          "id": 17,
          "name": "supercell",
          "label": "Supercell ID Gmail",
          "type": "text",
          "regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
        }
      ]
    },
    {
      "id": 55,
      "title": "Clash of Clans",
      "fields": [
        {
          "id": 18,
          "name": "player_tag",
          "label": "Player Tag",
          "type": "text",
          "regex": "^#[A-Z0-9]{4,10}$"
        }
      ]
    }
  ],
  "message": "Product Categories retrieved successfully."
}

cURL

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

Typical Errors

404 – No categories found

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

2. Get Products

GET /v1/products

▼

Query Parameters

Parameter	Type	Required	Description
`category_id`	integer	No	Filter products by category ID

Logic

Fetches all products or products filtered by category_id. Price is in partner's currency.

Request Example

GET /v1/products?category_id=54

Sample Response

{
  "success": true,
  "data": [
    {
      "id": 35,
      "name": "Brawl Stars - 30 Gems - 3.20 USD",
      "price": "3.20",
      "currency": "USD"
    },
    {
      "id": 36,
      "name": "Brawl Stars - 80 Gems - 8.00 USD",
      "price": "8.00",
      "currency": "USD"
    }
  ],
  "message": "Products retrieved successfully."
}

cURL

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

Typical Errors

404 – No products found in the category

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

3. Check Balance

GET /v1/check-balance

▼

Logic

Returns partner's current wallet balance and currency symbol.

Request Example

GET /v1/check-balance

Sample Response

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

cURL

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

4. Get Orders NEW

GET /v1/orders

▼

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `new`, `processing`, `completed`, `canceled`, `sign_in_verified`
`per_page`	integer	No	Items per page (default: 15, min: 1, max: 100)
`page`	integer	No	Page number (default: 1)

Logic

Returns paginated orders for the authenticated partner.
Optionally filter by order status.
Datetimes are returned in UTC (GMT+00) in human readable format.

Request Example

GET /v1/orders?status=processing&per_page=10&page=1

Sample Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 12345,
        "product_name": "Brawl Stars - 30 Gems",
        "status": "processing",
        "created_at": "2025-01-15 10:30:00 UTC",
        "updated_at": "2025-01-15 10:35:00 UTC"
      },
      {
        "id": 12344,
        "product_name": "Clash of Clans - 500 Gems",
        "status": "processing",
        "created_at": "2025-01-14 08:20:00 UTC",
        "updated_at": "2025-01-14 09:00:00 UTC"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total": 25,
      "last_page": 3
    }
  },
  "message": "Orders retrieved successfully."
}

cURL

curl -u username:password "https://supercell-api.apply.coupons/v1/orders?status=processing&per_page=10&page=1"

Typical Errors

422 – Invalid status value

{
  "success": false,
  "message": "Validation Error.",
  "data": {
    "status": ["The selected status is invalid."]
  }
}

5. Create Order

POST /v1/create-order

▼

Request Body Parameters

Parameter	Type	Required	Description
`product_id`	integer	Yes	ID of the product to order
`fields`	array	Yes	Array of field objects with `name` and `value`

Logic

Validates product, partner status, and balance.
Validates required fields (fields array) against product category's configuration (regex, etc.).
Creates an order with "processing" status and deducts the balance.
Sends a Telegram notification to admins.

Request Example

POST /v1/create-order

{
  "product_id": 35,
  "fields": [
    {"name": "supercell", "value": "[email protected]"}
  ]
}

Sample Response

{
  "success": true,
  "data": {
    "order_number": 12345
  },
  "message": "Order Created Successfully"
}

cURL

curl -u username:password -X POST https://supercell-api.apply.coupons/v1/create-order \
  -H "Content-Type: application/json" \
  -d '{"product_id":35,"fields":[{"name":"supercell","value":"[email protected]"}]}'

Typical Errors

402 – Insufficient Balance

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

404 – Product not found

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

422 – Validation Failed

{
  "success": false,
  "message": "Validation Error.",
  "data": { "fields.supercell": ["The Supercell ID Gmail field format is invalid."] }
}

6. Send Order OTP

POST /v1/send-order-otp

▼

Request Body Parameters

Parameter	Type	Required	Description
`order_id`	integer	Yes	ID of the order
`otp`	string	Yes	OTP code (4-10 characters)

Logic

Submits the One-Time Password (OTP) for an order that is in "processing" status.
Validates that the order belongs to the partner and hasn't already had an OTP submitted.

Request Example

POST /v1/send-order-otp

{
  "order_id": 12345,
  "otp": "123456"
}

Sample Response

{
  "success": true,
  "data": {
    "order_id": 12345,
    "otp": "123456"
  },
  "message": "OTP submitted successfully."
}

cURL

curl -u username:password -X POST https://supercell-api.apply.coupons/v1/send-order-otp \
  -H "Content-Type: application/json" \
  -d '{"order_id":12345,"otp":"123456"}'

Typical Errors

422 – Validation Failed

{
  "success": false,
  "message": "Validation Failed",
  "data": { "otp": ["Please enter the OTP code."] }
}

404 – Order not found

{ "success": false, "message": "Order not processing or exist" }

409 – Conflict (OTP already submitted)

{ "success": false, "message": "OTP has already been submitted." }

7. Cancel Order NEW

POST /v1/cancel-order

▼

Request Body Parameters

Parameter	Type	Required	Description
`order_id`	integer	Yes	ID of the order to cancel

Logic

Cancels an order that is in "processing" status.
Validates that the order belongs to the partner.
Order cannot be cancelled if OTP has already been submitted.
Balance is refunded upon successful cancellation.

Request Example

POST /v1/cancel-order

{
  "order_id": 12345
}

Sample Response

{
  "success": true,
  "data": {
    "order_id": 12345
  },
  "message": "Order cancelled successfully."
}

cURL

curl -u username:password -X POST https://supercell-api.apply.coupons/v1/cancel-order \
  -H "Content-Type: application/json" \
  -d '{"order_id":12345}'

Typical Errors

422 – Validation Failed

{
  "success": false,
  "message": "Validation Failed",
  "data": { "order_id": ["Order ID is required."] }
}

404 – Order not found or not in processing status

{ "success": false, "message": "Order not found or status is not processing." }

422 – OTP already submitted (cannot cancel)

{ "success": false, "message": "The OTP code has already been entered by the client!" }

Callback Information

▼

Webhook / Callback

POST Your Callback URL

▼

When an order's status is finalized (either completed or failed), our server will send a POST request to your registered callback URL. You must provide this URL to us.

Success Callback Payload

If the order is successfully completed, you will receive the following JSON payload:

{
  "success": true,
  "message": "Your order has been completed",
  "order_id": 12345
}

Fail Callback Payload

If the order fails for any reason (e.g., wrong OTP, item already exists), you will receive this payload structure:

{
  "error_code": "wrong_otp",
  "message": "Wrong OTP code. The OTP code is sent to the email address linked to your Supercell account.",
  "order_id": 12345
}

Callback Error Codes

The following are the possible error codes that can be sent in a fail callback:

Error Code	Description
`wrong_otp`	Wrong OTP code. The OTP code is sent to the email address linked to your Supercell account.
`wrong_account`	Wrong email address. You can reuse your voucher code after logging in to the correct email account.
`otp_not_entered`	OTP code not entered.
`item_already_exist`	This product already exists on your account. You can activate this product only once per account.
`event_not_exist`	This event already not exist.
`discount_not_exist`	This product is only available for accounts with an active discount. There is no discount on your account.