Retrieving a Single Coupon

This method returns the current state of one coupon together with every bet included in it.

Use it to:

• open a coupon detail page;
• check whether settlement is complete;
• retrieve the actual payout;
• restore complete information after a callback;
• check a specific coupon when data differs.

Method

GET /api/partner/coupons/get

The request requires a valid client-account Bearer JWT:

Authorization: Bearer <token>

Coupon parameter

Recommended parameter:

Example:

/api/partner/coupons/get?coupon_code=000000000272

The new endpoint also recognizes these compatible parameter names:

• code;
• coupon_id;
• bet_code.

Always use coupon_code for a new integration: it is the primary and clearest field name across all API methods.

Provide only one coupon-code parameter.

Leading zeros

Store and submit coupon_code as a string:

{
  "coupon_code": "000000000272"
}

This preserves leading zeros when the data is stored or transmitted.

The new API can pad a short numeric value with leading zeros to 12 digits:

272 → 000000000272

Nevertheless, always submit the complete 12-digit code. This avoids ambiguity in the partner database, logs, and requests between internal services.

Request example

HTTP:

GET /api/partner/coupons/get?coupon_code=000000000272 HTTP/1.1
Host: coupon-api.example.com
Authorization: Bearer <token>
Accept: application/json

cURL:

BASE_URL="https://coupon-api.example.com"
TOKEN="<jwt-token>"
COUPON_CODE="000000000272"

curl --request GET \
  --url "$BASE_URL/api/partner/coupons/get?coupon_code=$COUPON_CODE" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $TOKEN"

The partner receives the actual BASE_URL from the manager.

Successful response

The method returns the coupon directly in body:

{
  "code": 1,
  "body": {
    "coupon_code": "000000000272",
    "amount": 10,
    "win": 18.5,
    "potential_win": 18.5,
    "real_win": 18.5,
    "coef": 1.85,
    "original_coef": 1.85,
    "calculate_coef": 1.85,
    "has_return": false,
    "date": 1784970000000,
    "status": 2,
    "asian": false,
    "calculate_date": 1784973600000,
    "coupon_type": 1,
    "events_count": 1,
    "events_data": [
      {
        "id": 84521,
        "game_id": 737779544,
        "main_game_id": null,
        "is_sub_game": false,
        "parent_game_id": null,
        "sub_game_key": null,
        "raw_pointer": "line#737779544#1#1#0#1.85",
        "line_type": "line",
        "is_live": false,
        "bet_group_id": 1,
        "bet_group_name": "Match Result",
        "bet_id": 1,
        "bet_name": "First Team to Win",
        "sport_id": 1,
        "sport_name": "Football",
        "tournament_id": 45821,
        "tournament": "National League",
        "event_date": 1784971800000,
        "status": 1,
        "opp1": "Team A",
        "opp2": "Team B",
        "coef": 1.85,
        "calc_coef": 1.85,
        "calculate_date": 1784973600000,
        "calculate_score": "2:1",
        "settlement_reason_code": "AUTOMATIC_SETTLEMENT",
        "settlement_reason": "Calculated automatically",
        "rate": "0"
      }
    ]
  },
  "error_code": null,
  "error_message": null,
  "date": 1784973600100,
  "time_ms": 6,
  "path": "/api/partner/coupons/get"
}

The body object contains:

• general coupon data;
• stake and winnings values;
• original and settlement odds;
• status and dates;
• coupon type and number of bets;
• events_data with every coupon bet.

Each bet in events_data contains its own internal id, event and outcome data, odds, settlement status, dates, and score.

The example above is shortened to the primary bet fields. A complete field reference is provided in Coupon and bet model.

Important. For this method, body is a single coupon object. There is no body.coupons array. The array is used when placing coupons and in batch retrieval methods.

Determining the state

Primary fields to check:

Immediately after placement, a coupon usually contains:

{
  "status": 0,
  "real_win": null,
  "calculate_coef": null,
  "calculate_date": null
}

null means that the final value has not yet been formed. calculate_date is not 0 for an unsettled coupon.

Final coupon statuses are:

• 2 — win;
• 4 — loss;
• 8 — return.

Statuses 0 and 15 are not final. Status 15 means that the coupon was returned for recalculation, so wait for a new result.

Do not determine the result only from real_win. In an intermediate state, for example, it is not yet the final payout. Always check the coupon status.

The complete rules are described in Statuses and payout calculation.

Coupon and bet statuses are different

body.status belongs to the entire coupon, while body.events_data[].status belongs to an individual bet.

Coupon and bet status tables differ, so a code cannot be interpreted without considering its object. Examples of valid combinations:

Winning single:
coupon status = 2
bet status = 1

Losing single:
coupon status = 4
bet status = 2

Coupon returned for recalculation:
coupon status = 15
bet status = 4

Always interpret status in the context of the object containing the field.

Identifiers

Do not confuse these identifiers:

For local storage of a specific bet, use the combination:

coupon_code + events_data[].id

game_id and bet_id may occur in different coupons and do not replace the internal accepted-bet ID.

In a callback, the internal bet ID is provided as a string in events_data[].uuid.

Coupon not found

If the coupon does not exist or belongs to another partner, the API returns the same business error:

{
  "code": 0,
  "body": null,
  "error_code": 471,
  "error_message": "Coupon not found",
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/coupons/get"
}

The identical response does not reveal whether that code exists for another partner.

A partner can retrieve only its own coupons. Ownership is determined by the client account in the Bearer JWT, not by request parameters.

Checking for success

Do not check only for HTTP 200.

HTTP 2xx and code = 1 → coupon retrieved; process body
HTTP 2xx and code = 0 → business error; check error_code
HTTP 401 → JWT is missing, invalid, or expired
HTTP 403 → token does not have the required access
HTTP 5xx → temporary server error

When error_code = 471 is returned, do not create an empty coupon or replace a stored coupon record with empty data. First check the submitted coupon_code and verify that the JWT belongs to the required client account.

Compatible endpoints

The new endpoint has an alias with the same new response format:

GET /api/v3/partner/bet/get?coupon_code=000000000272

New integrations should use the canonical endpoint:

GET /api/partner/coupons/get?coupon_code=000000000272

The old API used:

GET /coupons/get?coupon_code=000000000272

The legacy endpoint remains supported, but returns the old response format and requires an exactly 12-digit code. An invalid code returns error_code = 560, and a coupon that is not found returns error_code = 561.

A complete contract comparison is provided in Migrating from the old API.

Checklist

• GET /api/partner/coupons/get is used.
• A valid Bearer JWT is provided.
• The parameter is named coupon_code.
• The code is stored as a string with leading zeros.
• Success is checked with code = 1.
• The coupon is read from the body object, not body.coupons.
• Coupon data and the entire events_data array are processed.
• Coupon and bet statuses are interpreted separately.
• The final real_win value is used for the payout.
• Status 15 is not treated as final.
• Error 471 is handled as no accessible coupon.

Next section: Retrieving coupons by list or time period.