[GET] Get Promotion IDs
Request Description
GET /v1/promotionThe request allows you to get a list of promotion identifiers that match the search criteria provided.
Connection Data
- Endpoint URL:
- Production environment: https://api.ecommerce.noventiq.com/v1/promotion
- Test environment: https://api.ecommerce.noventiq.com.demonqweb.com/v1/promotion
- Request Method: GET
- Authorization: token-based
Promotion quantity that should return in response.
If not transferred, the all promotions found will return in response.
If not transferred, the all promotions found will return in response.
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
Promotion status
A promotion can only be applied if it is active.
Value options:
A promotion can only be applied if it is active.
Value options:
- 1 - active
- 0 - inactive
Promotion expiration
Value options:
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
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.
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
You can enable sorting of identifiers by the date and time of their update (update_date) in response to the request
Value options:
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
Authorization token
- Format:
Bearer [token] - Where [token] is substituted by the token, value obtained through the authentication API
Request Example
- /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
Response Description
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.
Successful Response
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.
Offset
Starting promotion position followed by promotions that return in response.
Starting promotion position followed by promotions that return in response.
Response example: promotions are found
{
"count_all": 51,
"limit": 51,
"offset": 0,
"ids": [
444841127,
444652444,
666435276
]
}Response example: no promotions are found
{
"count_all": 0,
"limit": 0,
"offset": 0,
"ids": []
}Response example: no promotions are found. Invalid conditions for obtaining (offset>count_all)
{
"count_all": 108,
"limit": 0,
"offset": 150,
"ids": []
}
Error Response
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 Server Response Error Code
| 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. |
Additional Error Codes for HTTP 400
| 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. |
Additional Error Codes for HTTP 401
The errors are the same for all the APIs that use token authorization.
Example of Error Response
{
"errors": [{
"error": 11100,
"message": "Search is executed if string has at least three characters in it."
}
]
}