Skip to main content
GET
/
promotions
Get promotions
curl --request GET \
  --url https://edge.api.kelviq.com/api/v1/promotions \
  --header 'Authorization: Bearer <token>'
{
  "country": "India",
  "countryCode": "IN",
  "percentage": 40,
  "code": "KQP5LHNZB1Z",
  "message": "",
  "widgets": [
    {
      "type": "BANNER",
      "backgroundColor": "#3182CE",
      "fontColor": "#F9F9F9",
      "highlightFontColor": "#DD5C64",
      "fontSize": "1rem",
      "unStyled": false,
      "addCloseIcon": false,
      "countryMessage": "Hello {country_flag} Hey! It looks like you are from <b>{country}</b>. Use code <b>“{coupon_code}”</b> to get <b>{discount_percentage}%</b> off.",
      "placement": "top",
      "borderRadius": "0"
    }
  ],
  "security": {
    "proxy": false,
    "crawler": false,
    "vpn": false,
    "tor": false,
    "relay": false
  }
}

Authorizations

​
Authorization
string
header
required

The Server API Key obtained from the kelviq application. Pass as a Bearer token in the Authorization header. Example: 'Authorization: Bearer YOUR_API_KEY'

Query Parameters

​
promotion_id
string
required

The promotion ID from the Kelviq dashboard.

Response

Promotion data for the visitor's location

Promotion data resolved for the visitor's detected location.

​
country
string

Full name of the visitor's detected country.

Example:

"India"

​
countryCode
string

ISO 3166-1 alpha-2 country code.

Example:

"IN"

​
percentage
number

Discount percentage for the visitor's country. 0 means no active discount.

Example:

40

​
code
string

Coupon code the visitor can apply at checkout.

Example:

"KQP5LHNZB1Z"

​
message
string

Optional plain-text message. Usually empty — the banner message is in widgets[].countryMessage.

Example:

""

​
widgets
object[]

UI widgets configured for this promotion. Currently contains one BANNER widget.

​
security
object

Security check results for the visitor. true means the check flagged the request.