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

# Promotions & Banners

> Fetch targeted popup and banner campaigns and report client engagement events.

# Promotions & Banners

The Promotions service serves localized, prioritized marketing campaigns (popups and banners) to mobile and web clients, tracking impressions, clicks, and dismissals for conversion analytics.

***

## Get Active Promotions

Returns at most one high-priority `POPUP` and all active `BANNER` campaigns matching the user's country code and language tag. Country-specific campaigns take precedence over global campaigns.

### Endpoint

```http theme={null}
GET /api/v2/promotions/active
```

### Headers

```http theme={null}
Authorization: Bearer <jwt_access_token>
```

### Query Parameters

| Parameter  | Type     | Required | Description                                                   |
| :--------- | :------- | :------- | :------------------------------------------------------------ |
| `country`  | `string` | No       | ISO 3166-1 alpha-2 country code (e.g. `GH`, `NG`, `KE`, `US`) |
| `language` | `string` | No       | BCP 47 language tag (e.g. `en`, `fr`, `pt`)                   |

### Response (200 OK)

```json theme={null}
{
  "popup": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "title": "Summer Web3 Championship",
    "subtitle": "Compete for a 5,000 Gem Prize Pool!",
    "bodyText": "Join top Solidity developers in live quiz battles this weekend.",
    "imageUrl": "https://ik.imagekit.io/learnway/promotions/summer_champ.png",
    "ctaText": "Join Contest Now",
    "ctaAction": "NAVIGATE_CONTEST",
    "ctaPayload": { "contestId": "contest-uuid-1" },
    "priority": 100,
    "dismissible": true
  },
  "banners": [
    {
      "id": "a18b9c2d-3456-4abc-8def-1234567890cd",
      "title": "Upgrade to LearnWay Premium",
      "subtitle": "Get 50% off your annual subscription",
      "imageUrl": "https://ik.imagekit.io/learnway/promotions/premium_banner.png",
      "ctaText": "Upgrade",
      "ctaAction": "OPEN_SUBSCRIPTION_MODAL",
      "priority": 50
    }
  ]
}
```

***

## Track Campaign Event

Records user engagement (`IMPRESSION`, `CLICK`, or `DISMISS`) with a campaign. Designed to be called fire-and-forget by clients.

### Endpoint

```http theme={null}
POST /api/v2/promotions/:id/event
```

### Headers

```http theme={null}
Authorization: Bearer <jwt_access_token>
```

### Path Parameters

| Parameter | Type     | Required | Description   |
| :-------- | :------- | :------- | :------------ |
| `id`      | `string` | **Yes**  | Campaign UUID |

### Request Body

| Field       | Type     | Required | Description                         |
| :---------- | :------- | :------- | :---------------------------------- |
| `eventType` | `string` | **Yes**  | `IMPRESSION`, `CLICK`, or `DISMISS` |
| `country`   | `string` | No       | User's detected ISO country code    |

```json theme={null}
{
  "eventType": "CLICK",
  "country": "GH"
}
```

### Response (200 OK)

```json theme={null}
{
  "tracked": true
}
```