# Coupon API

> This section is intended for partners who accept sports bets in their own system, submit coupons to the SportAPI Coupon Settlement System, and receive their settlement results.

Version: v1
Language: en

## Documentation

- [API Overview](00-getting-started/01-overview.md): The Bet Placement and Settlement API allows a partner to submit sports bets selected by users to the SportAPI Coupon Settlement System (hereinafter referred to as the Settlement System), receive confirmation that the bets were accepted, and
- [Quick Start](00-getting-started/02-quick-start.md): This guide walks you through checking API availability, authenticating, placing a single coupon, and retrieving its current state.
- [Authentication](00-getting-started/03-authentication.md): To work with coupons and the balance, the partner must obtain a client JWT. The token is issued after the username and password are verified and determines which client’s data can be accessed.
- [Common API Conventions](00-getting-started/04-common-conventions.md): This page describes the conventions shared by all methods of the SportAPI Coupon Settlement System. Method-specific fields and business errors are documented on the corresponding method pages.
- [Bet Pointer](01-bet-placement/01-bet-pointer.md): A bet pointer is a string that uniquely describes the outcome selected by the user: the event, market, bet option, additional parameter, and odds.
- [Coupon Placement](01-bet-placement/02-place-coupon.md): Use the following endpoint to register the bets selected by a user:
- [Singles, Accumulators, and multi](01-bet-placement/03-coupon-types.md): The type of coupon created depends on the number of entries in listbets and the value of multi.
- [Odds Changes and Outcome Availability](01-bet-placement/04-coefficient-changes.md): The state of a sports-line outcome may change between the user selecting a bet and the coupon placement request being submitted:
- [Settlement Lifecycle](02-settlement/01-settlement-lifecycle.md): After a coupon is accepted, the SportAPI Coupon Settlement System tracks the results of all bets included in it and updates the coupon state.
- [Statuses and Payout Calculation](02-settlement/02-statuses-and-payouts.md): The coupon and every bet within it have their own status. Always interpret a status code according to the object to which the status field belongs.
- [Result Callbacks](02-settlement/03-callbacks.md): Callbacks allow the partner to receive coupon settlement changes without continuously polling the API.
- [Callback Signature Verification](02-settlement/04-callback-signature.md): Every callback is signed with HMAC-SHA256. Signature verification confirms that the request body was created by the SportAPI Coupon Settlement System and was not modified in transit.
- [Callback Retries and Idempotency](02-settlement/05-retries-and-idempotency.md): The same callback may be delivered more than once. This is a normal part of reliable delivery, not an error in the SportAPI Coupon Settlement System.
- [Polling Fallback](02-settlement/06-polling-fallback.md): Polling is the periodic retrieval of coupon states through the SportAPI Coupon Settlement System Client API.
- [Retrieving a Single Coupon](03-coupons/01-get-coupon.md): This method returns the current state of one coupon together with every bet included in it.
- [Retrieving Coupons by List or Time Period](03-coupons/02-query-results.md): One method can retrieve:
- [Active and Recently Settled Coupons](03-coupons/03-active-and-calculated.md): The SportAPI Coupon Settlement System provides two separate methods:
- [Coupon and Bet Model](03-coupons/04-coupon-model.md): The complete model contains:
- [Cashout](03-coupons/05-cashout.md): The current endpoint and response format may change after development and testing are complete.
- [End-to-End Example: Single](04-guides/01-single-bet.md): A single is a coupon containing one bet.
- [End-to-End Example: Accumulator](04-guides/02-accumulator.md): An accumulator is one coupon that combines several bets on different matches.
- [End-to-End Example: Recovery After a Missed Callback](04-guides/03-recovery.md): Callbacks speed up result delivery, but they are not the only source of data. The current coupon state is stored in the SportAPI Coupon Settlement System and is available through the Client API.
- [Endpoint Reference](05-reference/01-endpoints.md): Use the following routes for new integrations:
- [API Response Format](05-reference/02-response-format.md): The new Client API methods use a common JSON envelope.
- [Error Codes](05-reference/03-error-codes.md): The new Client API usually returns business errors with HTTP 200:
- [Migrating from the Legacy API](05-reference/04-migration-from-old-api.md): This document compares the legacy oldapicalc.txt description with Client OpenAPI 1.2.0. It is intended for existing integrators already using /api/v2/login, /bet/place, and /coupons/.
- [Compatible Legacy Routes](05-reference/05-legacy-api.md): Legacy routes remain supported, and there are currently no plans to remove them.
- [Glossary](05-reference/06-glossary.md): The set of HTTP methods through which a partner authenticates, creates coupons, and retrieves their states.
- [Changelog](05-reference/07-changelog.md): This page lists changes to the public Client API contract. New entries are added at the top and published together with the corresponding OpenAPI update.
- [Coupon API — callback and HMAC verification](06-examples/callback.md): Callbacks deliver coupon settlement changes without continuous API polling. The receiver verifies an HMAC-SHA256 signature calculated over the exact bytes of the JSON body.
- [Coupon API — cURL request examples](06-examples/curl.md): This page presents a verified flow: authenticate, retrieve a current outcome from Sport Line API, create the complete bet pointer, place a single, and retrieve the created coupon.
- [Coupon API — JavaScript example for Node.js](06-examples/javascript.md): This dependency-free example implements the complete flow: find current Sport Line API outcomes, authenticate with Coupon API, place a single, accumulator, or multiple singles, and retrieve their current state.
- [Full Coupon API JSON responses](06-examples/json-responses/README.md): These files contain complete, unabridged test Coupon API responses:
- [Coupon API — PHP example](06-examples/php.md): This PHP 8.1+ example implements the complete server-side flow: retrieve current outcomes, authenticate, place the selected coupon type, and query its state.
- [Coupon API — Python example](06-examples/python.md): This Python example retrieves Sport Line API outcomes, places a single, accumulator, or multiple singles, and queries the current coupon states.
- [Coupon API integration examples](06-examples/README.md): All examples use placeholders. Replace the base URLs, login, password, and Sport Line API key with values supplied by your SportAPI manager.
- [Odds, Bets, and Coupons — API Technical Documentation](QUICK-INTEGRATION.md): API version: 1.2.0.
- [Bet Placement and Settlement API](README.md): This section is intended for partners who accept sports bets in their own system, submit coupons to the SportAPI Coupon Settlement System, and receive their settlement results.
