Skip to main content
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

ParameterTypeRequiredDescription
periodKeystringNoFilter by period (e.g., 2026-03-18)
scopestringNoFilter by scope: global, category, offer, channel

​
Response

{
  "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

FieldTypeRequiredDescription
namestringYesBudget name (max 255 chars)
scopestringNoScope level: global, category, offer, channel (default: global)
scopeIdstringNoID of the scoped entity (required if scope is not global)
periodTypestringNoPeriod granularity: daily, weekly, monthly, quarterly (default: daily)
periodKeystringYesPeriod identifier (e.g., 2026-03-18, 2026-Q1)
maxImpressionsintegerNoMaximum impressions allowed
maxSpendnumberNoMaximum spend amount
maxConversionsintegerNoMaximum conversions allowed

​
Example

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

FieldTypeRequiredDescription
idstringYesBudget allocation ID
namestringNoUpdated name
scopestringNoUpdated scope
scopeIdstringNoUpdated scope entity ID
periodTypestringNoUpdated period type
periodKeystringNoUpdated period key
maxImpressionsintegerNoUpdated max impressions
maxSpendnumberNoUpdated max spend
maxConversionsintegerNoUpdated max conversions

​
DELETE /api/v1/budgets?id=

Delete a budget allocation. Admin only.

​
Query Parameters

ParameterTypeRequiredDescription
idstringYesBudget allocation ID

​
Response

{ "success": true }