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

# Budgets

> Manage budget allocations for offers, categories, and channels.

Budget allocations define spending and impression limits per time period. Budgets can be scoped globally or to a specific category, offer, or channel.

## GET /api/v1/budgets

List budget allocations for the tenant.

### Query Parameters

| Parameter   | Type   | Required | Description                                               |
| ----------- | ------ | -------- | --------------------------------------------------------- |
| `periodKey` | string | No       | Filter by period (e.g., `2026-03-18`)                     |
| `scope`     | string | No       | Filter by scope: `global`, `category`, `offer`, `channel` |

### Response

```json theme={null}
{
  "budgets": [
    {
      "id": "clx...",
      "name": "Q1 Email Budget",
      "scope": "channel",
      "scopeId": "ch_email",
      "periodType": "monthly",
      "periodKey": "2026-03",
      "maxImpressions": 50000,
      "maxSpend": 10000.00,
      "maxConversions": null,
      "tenantId": "my-tenant",
      "createdAt": "2026-03-01T00:00:00.000Z"
    }
  ],
  "count": 1
}
```

***

## POST /api/v1/budgets

Create a budget allocation. At least one limit (`maxImpressions`, `maxSpend`, or `maxConversions`) is required. **Editor or Admin.**

### Request Body

| Field            | Type    | Required | Description                                                                      |
| ---------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| `name`           | string  | Yes      | Budget name (max 255 chars)                                                      |
| `scope`          | string  | No       | Scope level: `global`, `category`, `offer`, `channel` (default: `global`)        |
| `scopeId`        | string  | No       | ID of the scoped entity (required if scope is not `global`)                      |
| `periodType`     | string  | No       | Period granularity: `daily`, `weekly`, `monthly`, `quarterly` (default: `daily`) |
| `periodKey`      | string  | Yes      | Period identifier (e.g., `2026-03-18`, `2026-Q1`)                                |
| `maxImpressions` | integer | No       | Maximum impressions allowed                                                      |
| `maxSpend`       | number  | No       | Maximum spend amount                                                             |
| `maxConversions` | integer | No       | Maximum conversions allowed                                                      |

### Example

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/budgets \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "name": "March Premium Card Budget",
    "scope": "offer",
    "scopeId": "offer_premium_card",
    "periodType": "monthly",
    "periodKey": "2026-03",
    "maxImpressions": 10000,
    "maxSpend": 5000
  }'
```

### Response (201)

Returns the created budget allocation object.

***

## PUT /api/v1/budgets

Update a budget allocation. **Editor or Admin.**

### Request Body

| Field            | Type    | Required | Description             |
| ---------------- | ------- | -------- | ----------------------- |
| `id`             | string  | Yes      | Budget allocation ID    |
| `name`           | string  | No       | Updated name            |
| `scope`          | string  | No       | Updated scope           |
| `scopeId`        | string  | No       | Updated scope entity ID |
| `periodType`     | string  | No       | Updated period type     |
| `periodKey`      | string  | No       | Updated period key      |
| `maxImpressions` | integer | No       | Updated max impressions |
| `maxSpend`       | number  | No       | Updated max spend       |
| `maxConversions` | integer | No       | Updated max conversions |

***

## DELETE /api/v1/budgets?id={id}

Delete a budget allocation. **Admin only.**

### Query Parameters

| Parameter | Type   | Required | Description          |
| --------- | ------ | -------- | -------------------- |
| `id`      | string | Yes      | Budget allocation ID |

### Response

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