Promotions

Manage commerce promotions (percent, fixed, or BOGO). Every promotion belongs to a campaign — use the campaigns tool first to obtain campaign_id.

Use action="create" (requires name, discount_type, discount_value, campaign_id). Use list/get to inspect. Use update/delete with id (alias: promotion_id). If applies_to="selected_items", pass catalog_item_ids and/or catalog_category_ids. For BOGO, required_items / required_categories are the buy-side; catalog_* ids are the get-side. usage_count is read-only. Checkout does not apply promo codes yet.

Input Schema

Parameter	Type	Description
action	string	create, list, get, update, delete
id	string	Promotion UUID (required for get, update, delete). Alias: `promotion_id`
promotion_id	string	Alias of `id`
site_id	string	Seller site UUID (defaults to current site)
user_id	string	Owner user UUID (defaults to site owner)
campaign_id	string	Campaign UUID (required for create)
name	string	Promotion name (required for create)
description	string	Promotion description
code	string	Optional promo code; unique per site when set
discount_type	string	percent, fixed, or bogo
discount_value	number	Percent 0-100, fixed amount, or BOGO marker
applies_to	string	all (default) or selected_items
min_order_amount	number	Minimum order amount to qualify
usage_limit	number	Global max redemptions
usage_limit_per_user	number	Per-user redemption cap
status	string	draft (default), active, paused, expired
starts_at	string	Validity start (ISO timestamptz)
ends_at	string	Validity end (ISO timestamptz)
channels	array	marketplace, shop, pos
location_ids	array	Optional business location UUIDs
active_weekdays	array	0-6 (Sun-Sat)
required_items_mode	string	all or any
bogo_buy_qty	number	BOGO buy quantity (default 1)
bogo_get_qty	number	BOGO get quantity (default 1)
image_url	string	Public image URL
show_on_shop	boolean	Show on shop
show_on_marketplace	boolean	Show on marketplace
currency	string	Currency code
catalog_item_ids	array	Item UUIDs the discount applies to (replace-if-provided on update)
catalog_category_ids	array	Category UUIDs the discount applies to
required_items	array	`{ catalog_item_id, min_quantity? }` required to qualify
required_categories	array	`{ catalog_category_id, min_quantity? }` required to qualify
search	string	Search name or code on list
active_now	boolean	On list, only promotions whose window includes now
limit	number	Max results for list
offset	number	Pagination offset

REST Endpoint


POST /api/agents/tools/promotions


POST /api/agents/tools/promotions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
 
{
  "action": "create",
  "site_id": "YOUR_SITE_ID",
  "campaign_id": "YOUR_CAMPAIGN_ID",
  "name": "20% off coffee",
  "discount_type": "percent",
  "discount_value": 20,
  "applies_to": "selected_items",
  "catalog_item_ids": ["CATALOG_ITEM_UUID"],
  "status": "active"
}

Response:


{
  "success": true,
  "promotion": {
    "id": "...",
    "name": "20% off coffee",
    "discount_type": "percent",
    "discount_value": 20,
    "status": "active",
    "catalog_items": [{ "id": "...", "catalog_item_id": "..." }]
  }
}