Knowledge Base
Noventiq Checkout
Up
Knowledge Base
Noventiq CheckoutIntegrationPromotions API
[POST] Get Promotion Statistics

[POST] Get Promotion Statistics

Request Description

POST /v1/promotion/statistics/

The request allows you to get information about how many times a promotion is applied. In addition, for promotions using promotion codes, the number of times each promotion code has been applied returns.

A promotion is considered applied if the customer created an order for a discounted product using a promotion. Payment for such an order is ignored.

If a product uses several promotions during the same period of time, then:

  • The customer gets a discount provided by only one of them. Discounts are not cumulative
  • Redemption is recorded for:
    • The promotion the discount of which was applied to the product
    • The rest of the promotions (see below for details), that were eligible but were not applied

Moreover:

  • The order status is ignored (i.e., the order can be unpaid/paid/deleted)
  • The redemption is recorded according to the products in the order. E.g., if there are two products in an order, and a discount amount is applied to each of them, this is counted as two redemptions of one promotion
  • The number of product units in the order is ignored. E.g., if there is 1 unit, or 5 units of the same product in an order, and a promotion is applied, this is counted as one redemption
  • If the promotion type is modified, the redemptions are not cancelled out. E.g., if the type of a promotion is changed from coupon to discount, the statistics will contain information about the redemptions of both - the promotional codes and the discounts

Connection Data

Header Parameters

content-type
required
MIME-type

It must be equal to "application/json".
AuthorizationJWT
required
Authorization token
  • Format: Bearer [token]
  • Where [token] is substituted by the token, value obtained through the authentication API

Body Parameters

id
string
required
Promotion identifier
You can get it from:

Request Example

{
 "id": 12345
}

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 ОК and the promotion redemption statistics in JSON format.

Body Parameters

promotion_uses
number
required
Number of promotion redemptions

Equals to 0 if the promotion has not been applied.
coupons
array [objects]
Promotion code redemption data
The array returns in response if a promotion has type coupon, or if this promotion had promotion codes bound to it earlier.

The parameter contains the array with the list of promotion codes.
The list includes:
  • All the promotion codes that currently belong to the promotion, and the statistics of their redemption. If any of the promotion codes has not yet been applied, it is present in the response having the number of redemptions equal to 0
  • All the promotion codes that belonged to the promotion, were applied, but then were deleted from the promotion.
    Note: This case is also possible if the promotion type was modified, i.e. changed from coupon to discount. If any of the promotion codes belonged to the promotion, but was not applied, it would not be present in the response
coupons / [object]
/
coupon_code
string
required
Promotion code
coupons / [object]
/
coupon_code
string
required
Promotion code type when applied

Value option:
  • one-time - in this case, the same promotion code can only be applied to the products of the same order. When managing a promotion through the portal, this type of promotion code is also called "disposable".
  • reusable - in this case, the same promotion code can be applied to the products of several different orders.
coupons / [object]
/
coupon_uses
number
required
Number of promotion code redemptions - within a promotion
coupons / [object]
/
coupon_id
number
required
Promotion code identifier

The system uses this identifier internally. The identifier is not customer-facing.

Possible case: a promotion code belonged to a promotion, then it was deleted and re-added with the same coupon_code value. If the case happens, the system will contain two different promotion codes having individual identifiers and separate statistics.

In this example, the number of redemptions of each promotion code does not match the number of redemptions of the promotion itself. That is so, because the type of the promotion has changed. Plus, the discount amount that was applied automatically without activating any promotion codes is counted.

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 or no promotion having the identifier transferred is found. If no promotion is found, an additional additional error code will return in the response body. 
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.
110 JSON is not valid. The request cannot be processed. Request field structure is not valid. Check the fields in the request body against the JSON format.
111 Invalid data format (Content-type). The request cannot be processed. Invalid request header. Content-type must be equal to application/json.
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: [parametr name] The request is not valid, e.g., the required parameter is not filled out, 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.

Additional Error Codes for HTTP 401

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

Additional Error Codes for HTTP 404

Error Message Description
11200 Promotion not found: [promotion id] No promotion with the identifier transferred is found, or you do not have the rights to get the data. 

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": 11200,
   "message": "Promotion not found: 123"
  }
 ]
}
Terms & Conditions
© 2024 Noventiq