[GET] Get promotion IDs

Request Description

GET /v1/promotion

The 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

URL Parameters

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.

Header Parameters

AuthorizationJWT

required

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.

Body Parameters

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)

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

Additional Error Codes for HTTP 400

Additional Error Codes for HTTP 401

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

Body Parameters

errors

array [objects]

required

Error list

errors / [error object] / error

number

required

Error code

errors / [error object] / message

string

Error description

Example of Error Response

{
 "errors": [{
   "error": 11100,
   "message": "Search is executed if string has at least three characters in it."
  }
 ]
}

Noventiq Checkout