> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kelviq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get promotions

> Resolves the active promotion for the caller's detected location. Returns the applicable discount percentage, coupon code, banner widget configuration, and security check results.

<Warning>Use your **Client API Key**, not your Server API Key. Find it under **Settings → API keys** in the Kelviq dashboard.</Warning>

<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>


## OpenAPI

````yaml /api-reference/openapi.json get /promotions
openapi: 3.0.0
info:
  title: kelviq API
  version: 1.0.0
  description: >-
    API for interacting with kelviq services, derived from Python SDK
    documentation.
servers:
  - url: https://sandboxapi.kelviq.com/api/v1
    description: Sandbox — Test payments
  - url: https://api.kelviq.com/api/v1
    description: Production — Live payments
security:
  - bearerAuth: []
tags:
  - name: Products
    description: Catalog products.
  - name: Product Settings
    description: Per-product settings (currency, VPN/Tor/proxy, product URL).
  - name: Product Files
    description: Product images and downloadable assets.
  - name: Features
    description: Catalog features that can be granted as plan entitlements.
  - name: Plans
    description: Catalog plans (CRUD, publish, versions, prices).
  - name: Plan Entitlements
    description: Feature entitlements attached to a plan.
  - name: Plan Files
    description: Files attached to plans, and signed download links.
  - name: Media
    description: Generate presigned S3 upload URLs for product/plan images and files.
  - name: Partner
    description: Partner integration APIs (organization provisioning, lookup).
  - name: Charges
    description: >-
      One-time payments charged immediately against a customer's default payment
      method.
  - name: Refunds
    description: Full and partial refunds for paid orders.
  - name: Payment Methods
    description: Saved customer payment methods (cards, etc.).
paths:
  /promotions:
    get:
      tags:
        - Promotions
      summary: Get promotions
      description: >-
        Resolves the active promotion for the caller's detected location.
        Returns the applicable discount percentage, coupon code, banner widget
        configuration, and security check results.


        <Warning>Use your **Client API Key**, not your Server API Key. Find it
        under **Settings → API keys** in the Kelviq dashboard.</Warning>
      operationId: getPromotion
      parameters:
        - name: promotion_id
          in: query
          required: true
          description: The promotion ID from the Kelviq dashboard.
          schema:
            type: string
          example: promo_abc123
      responses:
        '200':
          description: Promotion data for the visitor's location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromotionResponse'
              example:
                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
        '401':
          description: Unauthorized — missing or invalid API key
        '404':
          description: Promotion not found
      security:
        - bearerAuth: []
      servers:
        - url: https://edge.sandboxapi.kelviq.com/api/v1
          description: Sandbox — Test environment
        - url: https://edge.api.kelviq.com/api/v1
          description: Production — Live environment
components:
  schemas:
    PromotionResponse:
      type: object
      description: Promotion data resolved for the visitor's detected location.
      properties:
        country:
          type: string
          description: Full name of the visitor's detected country.
          example: India
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: IN
        percentage:
          type: number
          description: >-
            Discount percentage for the visitor's country. `0` means no active
            discount.
          example: 40
        code:
          type: string
          description: Coupon code the visitor can apply at checkout.
          example: KQP5LHNZB1Z
        message:
          type: string
          description: >-
            Optional plain-text message. Usually empty — the banner message is
            in `widgets[].countryMessage`.
          example: ''
        widgets:
          type: array
          description: >-
            UI widgets configured for this promotion. Currently contains one
            `BANNER` widget.
          items:
            $ref: '#/components/schemas/PromotionWidget'
        security:
          $ref: '#/components/schemas/PromotionSecurity'
    PromotionWidget:
      type: object
      description: Banner widget configuration returned by the promotion API.
      properties:
        type:
          type: string
          enum:
            - BANNER
          description: Widget type. Currently always `BANNER`.
          example: BANNER
        backgroundColor:
          type: string
          description: Banner background color (hex).
          example: '#3182CE'
        fontColor:
          type: string
          description: Main text color.
          example: '#F9F9F9'
        highlightFontColor:
          type: string
          description: Color for emphasized text such as the discount percentage.
          example: '#DD5C64'
        fontSize:
          type: string
          description: Font size as a CSS value.
          example: 1rem
        borderRadius:
          type: string
          description: Banner border radius as a CSS value.
          example: '0'
        placement:
          type: string
          enum:
            - top
            - bottom
          description: Viewport position of the banner.
          example: top
        unStyled:
          type: boolean
          description: >-
            When `true`, no default styles are injected. Apply your own CSS from
            scratch.
          example: false
        addCloseIcon:
          type: boolean
          description: When `true`, a close button is shown on the banner.
          example: false
        countryMessage:
          type: string
          description: >-
            Banner message template. Supports: `{country}`, `{country_flag}`,
            `{coupon_code}`, `{discount_percentage}`. HTML tags are allowed.
          example: >-
            Hello {country_flag} You're from <b>{country}</b>. Use code
            <b>"{coupon_code}"</b> for <b>{discount_percentage}%</b> off.
    PromotionSecurity:
      type: object
      description: >-
        Security check results for the visitor. `true` means the check flagged
        the request.
      properties:
        vpn:
          type: boolean
          description: '`true` if a VPN was detected.'
          example: false
        tor:
          type: boolean
          description: '`true` if Tor Browser was detected.'
          example: false
        proxy:
          type: boolean
          description: '`true` if a proxy server was detected.'
          example: false
        relay:
          type: boolean
          description: '`true` if Apple Private Relay was detected.'
          example: false
        crawler:
          type: boolean
          description: '`true` if the request is identified as a bot or crawler.'
          example: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The Server API Key obtained from the kelviq application. Pass as a
        Bearer token in the Authorization header. Example: 'Authorization:
        Bearer __YOUR_API_KEY__'

````