Offers API

Create, update, list, and delete offers (actions) in the KaireonAI platform.

See also: Offers concept and configuration for what this API powers, when to call it, and how it is configured.

Offers are the core decisioning entity in KaireonAI. Each offer represents a recommendation that can be scored, ranked, and delivered to a customer through one or more channels.

All offers support soft-delete (a deletedAt timestamp is set instead of permanent removal), version tracking (the version field auto-increments on every update), and audit logging (before/after snapshots are recorded for every CRUD operation).

See the Offers feature page for UI guidance and conceptual overview.

Base path

/api/v1/offers

---

List offers

GET /api/v1/offers

Returns a paginated list of offers for the current tenant, ordered by creation date (newest first). Each offer includes its creatives, category, and sub-category relations. By default, soft-deleted offers are excluded.

Query parameters

Parameter	Required	Type	Description
limit	No	integer	Maximum number of results to return. Default 25.
cursor	No	string	Cursor for keyset pagination. Pass the last id from the previous page.
includeDeleted	No	string	Set to "true" to include soft-deleted offers in the results.

Response 200

{
  "data": [
    {
      "id": "off_abc123",
      "tenantId": "t_001",
      "name": "Platinum Card Upgrade",
      "status": "active",
      "categoryId": "cat_01",
      "subCategoryId": "sub_01",
      "category": "acquisition",
      "group": "",
      "priority": 75,
      "businessValue": 50,
      "mandatory": false,
      "mandatoryReason": null,
      "mandatoryExpiresAt": null,
      "mandatoryApprovedBy": null,
      "emergencyExcluded": false,
      "description": "Premium card upgrade offer for high-value customers.",
      "shortDesc": "Upgrade to Platinum",
      "eligibility": {},
      "budget": { "maxPerDay": 500 },
      "schedule": {},
      "tags": ["credit-card", "premium"],
      "productType": "credit_card",
      "margin": null,
      "revenueValue": null,
      "metadata": {},
      "version": 1,
      "deletedAt": null,
      "creatives": [],
      "categoryRef": { "id": "cat_01", "name": "Acquisition" },
      "subCategoryRef": null,
      "createdAt": "2026-03-10T12:00:00.000Z",
      "updatedAt": "2026-03-12T09:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 25,
    "hasMore": true,
    "nextCursor": "off_xyz789"
  }
}

Error codes

Code	Reason
401	Missing or invalid API key / session.
403	Insufficient role.
429	Rate limit exceeded (2,000 requests / 60 s).

---

Create an offer

POST /api/v1/offers

Creates a new Offer. Triggers auto-assembly on any active Decision Flows.

Request body

Field	Required	Type	Description
name	Yes	string (1-255)	Unique offer name.
status	No	enum	draft (default), active, paused, archived.
categoryId	No	string | null	ID of the parent category.
subCategoryId	No	string | null	ID of the parent sub-category.
category	No	string	Legacy category label. Default "engagement".
group	No	string	Legacy group label. Default "".
priority	No	integer (0-100)	Offer priority. Default 50.
businessValue	No	number (0-100)	Business value score. Default 50.
mandatory	No	boolean	Mark as mandatory (admin-only). Default false.
mandatoryReason	No	string | null	Required when mandatory is true.
mandatoryExpiresAt	No	string | null	ISO 8601 expiry. Required when mandatory is true.
mandatoryApprovedBy	No	string | null	Approver ID. Required when mandatory is true.
emergencyExcluded	No	boolean	Emergency exclusion flag. Default false.
description	No	string	Full description.
shortDesc	No	string	Short description for cards/lists.
eligibility	No	object	Eligibility rule config.
budget	No	object	Budget constraints.
schedule	No	object	Scheduling config.
tags	No	string[]	Free-form tags.
productType	No	string	Product type label (e.g., "credit_card", "loan"). Used by PRIE scoring for relevance matching.
margin	No	number	Profit margin value. Feeds into the Impact (I) component of PRIE scoring.
revenueValue	No	number	Expected revenue value. Feeds into the Impact (I) component of PRIE scoring.
metadata	No	object	Arbitrary key-value metadata.

Setting mandatory to true requires the admin role and all three governance fields: mandatoryReason, mandatoryExpiresAt, and mandatoryApprovedBy. Server-side validations enforce:

• mandatoryExpiresAt must parse to a valid date and be strictly in the future (creates fail with 400 otherwise).
• mandatoryApprovedBy must reference a real user in the same tenant.
• That user must have role admin (rejecting attempts to set non-admin approvers).

Example request

{
  "name": "Platinum Card Upgrade",
  "status": "draft",
  "categoryId": "cat_01",
  "priority": 75,
  "description": "Premium card upgrade for high-value customers.",
  "tags": ["credit-card", "premium"],
  "budget": { "maxPerDay": 500 }
}

Response 201

Returns the created offer object with all relations, version: 1, and deletedAt: null. An audit log entry is created with a create action.

Error codes

Code	Reason
400	Validation error (missing name, invalid fields, mandatory fields missing).
401	Missing or invalid API key / session.
403	Non-admin trying to create mandatory offer.
409	An offer with that name already exists.
415	Content-Type is not application/json.

---

Update an offer

PUT /api/v1/offers

Updates an existing offer. Only provided fields are changed. Triggers auto-assembly on status transitions. The version field is auto-incremented and a before/after audit snapshot is recorded.

Request body

All fields from the create schema are accepted as optional, plus:

Field	Required	Type	Description
id	Yes	string	The offer ID to update.

Example request

{
  "id": "off_abc123",
  "status": "active",
  "priority": 90
}

Response 200

Returns the updated offer object with the incremented version.

Error codes

Code	Reason
400	Validation error.
401	Missing or invalid API key / session.
403	Non-admin trying to set mandatory.
409	Name conflict.

---

Delete an offer (soft-delete)

DELETE /api/v1/offers?id={offerId}

Soft-deletes an offer by setting its deletedAt timestamp. Cascade behavior: all associated creatives are also soft-deleted. The version is incremented on the offer and each cascaded creative. An audit log entry is recorded for every affected entity.

Query parameters

Parameter	Required	Type	Description
id	Yes	string	Offer ID to delete.

Response 200

{
  "success": true,
  "id": "off_abc123",
  "cascaded": 3
}

The cascaded field indicates how many child creatives were also soft-deleted.

Error codes

Code	Reason
400	Missing id query parameter, entity not found, or entity already deleted.
401	Missing or invalid API key / session.
403	Insufficient role.

To restore a soft-deleted offer, use POST /api/v1/restore?entityType=offer&id={offerId} (admin only). Restoring an offer does not automatically restore cascaded creatives — you must restore them individually.

---

Role requirements

Method	Minimum role
GET	viewer
POST	editor
PUT	editor
DELETE	editor

Offers

Learn more about creating and managing offers in the platform UI.