Перейти к содержанию

Loyalty Online API v1.2.0

Loyalty cards issuance and maintenance.

General information

The manual is intended for partner companies of Bescontact LLC that want to organize loyalty cards issuance in the Koshelek mobile application using the Koshelek platform.

Loyalty Online API allows to implement the main set of user scenarios of a loyalty card life cycle in the Koshelek App.

Updates: Loyalty API v1.1.0 → v1.2.0

  • Introduced new method POST /v1/card/anonymous that implements loyalty card issuance without pre-reservation of anonymous card number.

API demo zone

The demo zone for testing Loyalty Online API scenarios can be found here:


API service is partner hosted

A web service implementing the Loyalty Online API is deployed at the partner’s host and must be integrated with partner’s CRM system according to Koshelek Developers documentation. For messaging, the standard RESTful model is used, the data is transmitted in JSON format via the HTTPS protocol:

Loyalty Online API_en

As the web service implementing the API is deployed at partner’s host, the following data must be presented to Koshelek:

Parameter Description
host:port Address of the partner’s host providing the API.
login:password Username and password to authorize API requests from Koshelek.


The HTTPS protocol is used. HTTP Basic Authentication (RFC 7617) mechanism should be used for API requests authorization. Credentials for authorization are transferred at the Authorization HTTP header.


Both API requests and responses should use UTF-8 encoding.

Message structure

1. Headers

Responses from the partner’s side must contain the following header:

Content-Type: application/json; charset=utf-8;

2. Response body

The response body from the partner must comply with the response requirements specified in the description of the corresponding request.

HTTP codes

Responses from the partner’s side must use the following HTTP codes:

Code Description
200 API request successfully processed.
422 An error occurred while processing the request.


In case of error the partner’s side must return a JSON object containing the error code and description.

Response example:

HTTP/1.1 422 Unprocessable Entity

    "code": "123",
    "description": "DBMS server unavailable"

Please note:

The API assumes that all “elementary” fields of JSON objects returned in responses have a string type, even if they contain values of other types (numeric, Boolean, etc.)

See the example of returning a numerical error code above.