Retrieving Coupons by List or Time Period

One method can retrieve:

• known coupons from a list of coupon_code values;
• coupons placed during a specified period.

These modes are mutually exclusive: select only one in each request.

Method

POST /api/partner/coupons/results

The request requires:

Authorization: Bearer <token>
Content-Type: application/json

Selecting a mode

Do not submit coupon_ids together with start_date or end_date.

An invalid parameter combination returns business error 1002.

Mode 1. Retrieving by code

Submit the coupon_ids array:

POST /api/partner/coupons/results HTTP/1.1
Host: coupon-api.example.com
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "coupon_ids": [
    "000000000272",
    "000000000273"
  ]
}

Parameters

One request may contain no more than 100 codes.

Store and submit every coupon_code as a string to preserve leading zeros:

{
  "coupon_ids": [
    "000000000272"
  ]
}

Result behavior

When processing the list, the API:

• removes duplicate codes;
• does not return unknown coupons;
• does not return coupons belonging to other partners;
• may return coupons in a different order;
• may return fewer entries than were submitted.

Therefore, do not match request and response entries by index:

coupon_ids[0] ↛ body.coupons[0]

Always find and update a coupon by its coupon_code.

To check more than 100 coupons, split the list into multiple requests.

cURL example

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

curl --request POST \
  --url "$BASE_URL/api/partner/coupons/results" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "coupon_ids": [
      "000000000272",
      "000000000273"
    ]
  }'

The partner receives the actual BASE_URL from the manager.

Mode 2. Retrieving by placement period

Submit both period boundaries:

POST /api/partner/coupons/results HTTP/1.1
Host: coupon-api.example.com
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "start_date": 1784880000000,
  "end_date": 1784966400000
}

Parameters

Rules:

• both dates are required;
• end_date must be greater than start_date;
• the interval cannot exceed 24 hours;
• values are provided in milliseconds, not seconds.

Example interval of exactly 24 hours:

start_date = 1784880000000
end_date   = 1784966400000
difference = 86,400,000 ms

To request a longer period, divide it into consecutive intervals of no more than 24 hours each.

Selection uses placement time

The method compares the period with the coupon placement time, not its settlement date.

For example:

coupon placed: July 20
coupon settled: July 22

A placement-period request for July 22 will not return this coupon. To find results that appeared recently, use GET /api/partner/coupons/calculated.

Searching by placement period is suitable for:

• restoring coupons placed during an outage;
• reconciling history for a known day or interval;
• retrieving coupons when their codes were not stored locally.

Successful response

Both modes return the same response structure:

{
  "code": 1,
  "body": {
    "query_type": "ids",
    "coupons": [
      {
        "coupon_code": "000000000272",
        "amount": 10,
        "potential_win": 18.5,
        "real_win": 18.5,
        "original_coef": 1.85,
        "calculate_coef": 1.85,
        "status": 2,
        "calculate_date": 1784973600000,
        "coupon_type": 1,
        "events_count": 1,
        "events_data": [
          {
            "id": 84521,
            "game_id": 737779544,
            "bet_id": 1,
            "bet_name": "First Team to Win",
            "status": 1,
            "coef": 1.85,
            "calc_coef": 1.85,
            "calculate_date": 1784973600000,
            "calculate_score": "2:1",
            "settlement_reason_code": "AUTOMATIC_SETTLEMENT",
            "settlement_reason": "Calculated automatically"
          }
        ]
      }
    ]
  },
  "error_code": null,
  "error_message": null,
  "date": 1784973600100,
  "time_ms": 8,
  "path": "/api/partner/coupons/results"
}

body.coupons is an array containing complete current coupon models. Every coupon contains an events_data array with its bets.

The example is shortened to the primary fields. The complete structure is described in Coupon and bet model.

The query_type field

This field indicates which request mode was processed:

Do not submit query_type in the request. The API creates it in the response.

Empty result

A successful request may return an empty array:

{
  "code": 1,
  "body": {
    "query_type": "ids",
    "coupons": []
  },
  "error_code": null,
  "error_message": null
}

This is not an error.

For ids mode, an empty array means that none of the submitted codes identify coupons accessible to the current client account.

For time mode, it means that no accessible coupons were placed during the specified period.

Parameter error

For an invalid parameter combination, the API returns:

{
  "code": 0,
  "body": null,
  "error_code": 1002,
  "error_message": "<parameter error description>",
  "date": 1784970000000,
  "time_ms": 4,
  "path": "/api/partner/coupons/results"
}

Error 1002 may be returned when, for example:

• coupon_ids and dates are submitted together;
• only one period boundary is provided;
• the date interval is not positive;
• the interval exceeds 24 hours;
• the parameters do not identify a request mode.

error_message may clarify the specific reason. In program logic, use error_code as the primary indicator.

Checking for success

As with other new API methods, HTTP 200 alone does not indicate a successful business operation:

HTTP 2xx and code = 1 → request succeeded; process body.coupons
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

Process the entire body.coupons array, not only the first entry.

Storing the result

Recommended algorithm:

1. check the HTTP status and code;
2. check body.query_type;
3. iterate over the entire body.coupons array;
4. find the local record by coupon_code;
5. update the coupon-level data;
6. update bets by coupon_code + events_data[].id;
7. perform a financial action only for a settlement state not yet processed.

Receiving a coupon again does not mean a new bet. Requests by code, requests by period, polling, and callbacks may return different current snapshots of the same coupon_code.

Difference from retrieving one coupon

To retrieve only one known coupon and handle its absence explicitly, use Retrieving a single coupon.

Relationship to polling

The coupon_ids mode is suitable for restoring known coupons after an extended outage.

The date mode does not search by settlement time. For regular retrieval of recent results, use:

GET /api/partner/coupons/calculated?time={minutes}

The practical overlapping-window flow is described in Polling fallback.

Legacy API note

The old API used the following endpoint to retrieve coupons for a period:

GET /coupons/list

The legacy endpoint remains supported, but returns the old coupon model and uses a different parameter contract.

Use POST /api/partner/coupons/results in the new API. A detailed list of changes is provided in Migrating from the old API.

Checklist

• POST /api/partner/coupons/results is used.
• A Bearer JWT and Content-Type: application/json are provided.
• Only one request mode is selected.
• coupon_ids contains no more than 100 codes.
• Coupon codes are stored as strings.
• Both dates are submitted as Unix milliseconds for period mode.
• The interval is positive and does not exceed 24 hours.
• The period is understood to refer to placement time.
• Results are matched by coupon_code, not by position.
• An empty array is handled as a successful result.
• The entire body.coupons array and all events_data entries are processed.
• Financial operations remain idempotent.

Next section: Active and recently settled coupons.