Coupon and Bet Model

The complete model contains:

• general coupon data;
• amounts and odds;
• status and settlement dates;
• the events_data array with every coupon bet.

One events_data object describes one accepted bet within the coupon.

General structure

{
  "coupon_code": "000000000272",
  "amount": 10,
  "status": 0,
  "events_count": 1,
  "events_data": [
    {
      "id": 84521,
      "game_id": 737779544,
      "bet_id": 1,
      "status": 0
    }
  ]
}

Coupon and bet statuses use different reference tables. Always consider the level at which the field appears.

Identifiers

Do not confuse these values:

coupon_code → coupon
id / uuid   → specific bet within the coupon
game_id     → sporting event
bet_id      → outcome in the sports line
batchId     → callback batch

For local bet storage, use this composite key:

coupon_code + events_data[].id

When processing a callback, match the string uuid to the stored id.

game_id and bet_id may repeat across different coupons, so they do not replace the internal accepted-bet ID.

Coupon fields

General data

events_count should describe the number of bet objects, but always iterate over the actual events_data array when processing a response.

Amounts

Use real_win for financial crediting after final settlement.

Do not use potential_win as the actual payout. It is only the potential result calculated when the coupon was placed.

In brief:

amount        → amount staked
potential_win → amount that could be received at placement time
real_win      → amount actually payable after settlement

The win field is retained for display and compatibility. When the partner needs to change the user balance, real_win should be the primary field.

Coupon odds

In brief:

original_coef  → odds at placement time
coef           → current displayed value
calculate_coef → final settlement multiplier

For a financial operation, do not independently recalculate the payout from the displayed coef. Use the provided real_win value.

Settlement date

Before settlement, the value is always null:

{
  "calculate_date": null
}

The value 0 is not used for an unsettled coupon.

Coupon statuses

Status 15 does not mean a regular card update. The corresponding bet has status 4, and the partner waits for a new settlement result.

Financial actions for these statuses are described in Statuses and payout calculation.

Bet fields in events_data

Event and sub-event IDs

For a main game, some sub-event fields are null.

Main game example:

{
  "game_id": 737779544,
  "main_game_id": 737779544,
  "is_sub_game": false,
  "parent_game_id": null,
  "sub_game_key": null,
  "dop_name": null
}

For a sub-event, game_id identifies the selected sub-event, while main_game_id and parent_game_id associate it with the main match.

Original pointer and sports line type

raw_pointer is stored without modification:

line#737779544#1#1#0#1.85

It is useful for technical reconciliation, but does not replace events_data[].id as the accepted-bet ID.

Sport, tournament, and participants

opp_icon1 and opp_icon2 are legacy-compatible names. Despite the word icon, these fields contain participant IDs, not an image URL or file.

Use team1_id and team2_id in new code.

Bet group and outcome

bet_name may already include the resolved outcome parameter and player name when applicable.

Example:

{
  "bet_group_id": 17,
  "bet_group_name": "Goal Totals",
  "bet_id": 9,
  "bet_name": "Total Over 2.5",
  "rate": "2.5"
}

Bet odds and settlement

calc_coef depends on the bet result:

calc_coef is the settlement multiplier of a specific bet, while coupon-level calculate_coef is the result for the entire coupon.

Settlement reason

The reason fields supplement the numeric bet status:

• settlement_reason_code is suitable for program processing and analytics;
• settlement_reason contains explanatory text and is not a stable program value.

Example codes:

The list of codes may grow. Do not reject a response because of an unknown settlement_reason_code: store the value and determine the financial result from status, calc_coef, and the final real_win.

End-user notification

For a clear interface message:

1. read settlement_reason_code;
2. map a known code to the partner’s localized text;
3. if the code is unknown, use a non-empty settlement_reason as a fallback explanation;
4. store both original fields for subsequent reconciliation.

For example:

Do not assume that settlement_reason is translated into the coupon language: the field may contain the original text from the settlement source. The reason explains the result and does not replace status, calc_coef, or real_win.

These fields describe the reason for a completed settlement or return, not the current state of the sporting event. Both fields are null before settlement; the API does not guarantee a separate advance notification of a postponed or cancelled match through these fields.

Event score

Important. Despite its name, bet_score is not the match score. It is a compatibility field containing the original bet pointer. Use calculate_score and the extended placement_* / calculation_* fields for scores.

The score format depends on the sport and provider data. Store it as a string and do not independently determine the bet result from this field alone.

Complete active coupon example

{
  "coupon_code": "000000000272",
  "amount": 10,
  "win": 18.5,
  "potential_win": 18.5,
  "real_win": null,
  "coef": 1.85,
  "original_coef": 1.85,
  "calculate_coef": null,
  "has_return": false,
  "date": 1784970000000,
  "status": 0,
  "asian": false,
  "calculate_date": null,
  "coupon_type": 1,
  "events_count": 1,
  "events_data": [
    {
      "id": 84521,
      "game_id": 737779544,
      "main_game_id": 737779544,
      "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": 10001,
      "tournament": "National League",
      "event_date": 1784971800000,
      "status": 0,
      "opp1": "Team A",
      "opp2": "Team B",
      "coef": 1.85,
      "calc_coef": null,
      "bet_score": "line#737779544#1#1#0#1.85",
      "calculate_date": null,
      "calculate_score": null,
      "settlement_reason_code": null,
      "settlement_reason": null,
      "placement_score_full": null,
      "placement_score_periods": null,
      "calculation_score_full": null,
      "calculation_score_periods": null,
      "timer": null,
      "dop_name": null,
      "rate": "0",
      "sgame_id": null,
      "game_num": null,
      "stat_id": null,
      "team1_id": 101,
      "team2_id": 102,
      "opp_icon1": 101,
      "opp_icon2": 102
    }
  ]
}

After a single wins, the primary settlement fields change:

{
  "status": 2,
  "real_win": 18.5,
  "calculate_coef": 1.85,
  "calculate_date": 1784973600000,
  "events_data": [
    {
      "id": 84521,
      "status": 1,
      "calc_coef": 1.85,
      "calculate_date": 1784973600000,
      "calculate_score": "2:1",
      "settlement_reason_code": "AUTOMATIC_SETTLEMENT",
      "settlement_reason": "Calculated automatically",
      "calculation_score_full": "2:1"
    }
  ]
}

This is a shortened snapshot of the changes, not a separate response format.

Nullable fields

null is a normal value when data:

• has not yet been calculated;
• does not apply to the particular sport;
• is unavailable from the provider;
• applies only to live betting or sub-events.

Do not automatically replace null with numeric 0 or an empty string: these values may have a different meaning in the contract.

It is particularly important to preserve:

real_win = null before final settlement
calculate_coef = null before final settlement
calculate_date = null before settlement
calc_coef = null before bet settlement
settlement_reason_code = null before bet settlement
settlement_reason = null before bet settlement

Dates and decimal values

All dates in this model are Unix timestamps in milliseconds:

1784973600000

Do not confuse them with Unix timestamps in seconds.

Amounts and odds are decimal numbers without a fixed number of decimal places. The partner defines the display and rounding rules in its own system.

Use a decimal data type rather than a binary float to store money and perform financial calculations.

Language of names

Sport, tournament, participant, bet group, and outcome names use the lang specified when the coupon was placed.

The API supports approximately 50 languages. Submit a two-letter language code; the full list is not published in this documentation.

The language is fixed when the coupon is placed. An existing coupon cannot currently be retrieved in another translation. Support for multiple language variants of one coupon is in development.

Differences between the full model and callback

A callback provides a settlement snapshot rather than the complete coupon record.

Callbacks do not include, in particular:

• amount;
• sport, tournament, team, market, and outcome names;
• some original coupon data.

If callback processing requires missing fields, store them when the coupon is placed or retrieve the full model through the Client API.

Currency

The currency field is submitted when placing a coupon but is not included in the full coupon response model or callbacks.

If the partner needs to display the currency or associate financial operations with it, store the submitted currency value in the partner’s system after successful coupon placement.

Any string identifier for a regular, virtual, internal, or fictional currency is supported.

Recommended stored data

The partner decides which data is required. For a reliable integration, store at least:

Coupon level

• coupon_code;
• amount;
• the currency submitted at placement, when used;
• coupon_type;
• status;
• real_win;
• original_coef;
• calculate_coef;
• date;
• calculate_date.

Bet level

• coupon_code;
• events_data[].id;
• raw_pointer;
• game_id;
• bet_group_id;
• bet_id;
• coef;
• status;
• calc_coef;
• calculate_date;
• settlement_reason_code;
• settlement_reason when the text is required for logs or display.

For display, also store the required names, participants, and score data.

Storing the entire response is optional. However, coupon_code must always be stored: it is the primary linking key between the partner’s system and the SportAPI Coupon Settlement System.

Checklist

• coupon_code is stored as a string with leading zeros.
• Coupons and bets are stored as separate related entities.
• A bet is identified by coupon_code + id.
• Callback uuid is matched to full-model id.
• batchId is not used as a coupon or bet ID.
• real_win is used for the final payout.
• potential_win is not used as the actual payout.
• Coupon and bet statuses are read from different reference tables.
• calculate_date is null, not 0, before settlement.
• bet_score is not interpreted as the match score.
• Nullable fields are handled without artificial value substitution.
• settlement_reason_code, not settlement_reason text, is used for reason logic.
• Dates are read as Unix milliseconds.
• The partner stores currency at placement when required.
• The language of names is fixed when the coupon is placed.

Next section: Cashout.