Contents

Get Promotion IDs

GET /v1/promotion

The request allows you to get a list of promotion identifiers that match the search criteria provided.

limit
number
Promotion quantity that should return in response.
If not transferred, the all promotions found will return in response.
offset
number
Offset: by how many promotions you want to shift result outputting
  • If not transferred or equal to 0, you will get the list that starts from the 1st promotion found
  • For example, if 10 is transferred, you will get the list that starts from the 11th promotion found
status
number
Promotion status
A promotion can only be applied if it is active.

Value options:
  • 1 - active
  • 0 - inactive
If not transferred, the promotions having any status return in response.
expired
number
Promotion expiration

Value options:
  • 1 - promotion expired, promotion expiration (end) date and time [date_to] > current date and time
  • 0 - promotion has not expired. Promotion expiration (end) date and time [date_to] ≤ current date and time
If not transferred, the promotions having any expiration dates return in response.
search_string
string
Search keyword string
If transferred, the promotions having an occurrence of the string value in the promotion name (promotion_name) return in response.

Not less than 3 characters.
sort_by_update_date
string
Sort by update_date
You can enable sorting of identifiers by the date and time of their update (update_date) in response to the request

Value options:
  • desc - sorting by update date in descending order (from latest to earliest), for example: 01.01.2022 00:00:00 > 01.01.2022 00:00:00
  • asc - sorting by update date in ascending order (from earliest to latest), for example: 01.01.2022 00:00:00 > 01.01.2022 00:00:00
By default, if sorting is not specified by the sort_by_update_date parameter, IDs are sorted from the largest number to the smallest one.
AuthorizationJWT
required
Authorization token
  • Format: Bearer [token]
  • Where [token] is substituted by the token, value obtained through the authentication API
  • /v1/promotion
    All the promotions that are available. The list is sorted by promotion IDs in descending order
  • /v1/promotion?search_string=Black%20Friday
    All the available promotions that have "Black Friday" in the promotion name (promotion_name)
  • /v1/promotion?expired=1
    All the promotions that have expired
  • /v1/promotion?status=1&expired=0
    All the promotions that are active and have not yet expired (or their validity period haven't started yet)
  • /v1/promotion?limit=10&offset=5&sort_by_update_date=desc
    10 promotions starting from the 6th one; sorted by the update date in descending order

In response to the request, you receive the server response code corresponding to the processing result. Depending on the code, the response body may contain additional parameters.

If processing is successful, the following will return in response server response code: HTTP/1.1 200 ОК. Response body: list of found promotion IDs in JSON format.

count_all
number
required
Number of promotions found
limit
number
required
Promotion quantity in response
offset
string
required
Offset
Starting promotion position followed by promotions that return in response.
ids
array [numbers]
required
Array of promotion IDs
The array may return empty if no promotions are found, e.g.:
  • Promotions not found
  • Offset (offset)is greater than available promotion quantity (count_all)
{
 "count_all": 51,
 "limit": 51,
 "offset": 0,
 "ids": [
  444841127,
  444652444,
  666435276
 ]
}
{
 "count_all": 0,
 "limit": 0,
 "offset": 0,
 "ids": []
}
{
 "count_all": 108,
 "limit": 0,
 "offset": 150,
 "ids": []
}

If an error occurs while processing the request, you receive a server response code corresponding to the result of processing. 
Depending on the code, the response body may contain additional parameters.

HTTP code Description
HTTP/1.1 400 Bad Request The request is not valid (error in parameters; necessary data is not transferred, etc.).
An additional error code (one or more) will be transferred in the response bodу.
HTTP/1.1 401 Unauthorized Unsuccessful authorization.
An additional error code (one or more) will be transferred in the response bodу.
HTTP/1.1 404 Not found Invalid request URL.
HTTP/1.1 500 Request Error Internal Server Error. Please try again later or contact support.
Error Message Description
If at least one error from the list below is found, then it returns in response to a request, other errors are not validated.
11000 No access to promotion management. Please contact technical support. During processing, we could not identify your account setting unambiguously. Please contact support team.
If at least one error from the list below is found, then request validation is not interrupted. Several errors may return in response.
11010 Invalid field value: [parameter name].

The request is not valid, e.g., the parameter name is incorrect, the parameter value does not match with the data type provided, or the value format is incorrect. Moreover, the error will return if null is transferred in the parameter, and this value option is not set as valid in the parameter description.

11100 Search is executed if string has at least three characters in it.

The search_string is transferred in the request, but its value is less than 3 characters.

The errors are the same for all the APIs that use token authorization.

errors
array [objects]
required
Error list
errors / [error object]
/
error
number
required
Error code
errors / [error object]
/
message
string
Error description
{
 "errors": [{
   "error": 11100,
   "message": "Search is executed if string has at least three characters in it."
  }
 ]
}