Create a partner group

POST /program/affiliates/groups

Scope	program:write
Customer session token	Not accepted: call from your server with an API key
Rate limit class	write (limits)
Idempotency key	Required (idempotency)
MCP tool	charm_create_affiliate_group

A group with its own rates and buyer discount. Assigning partners to it is done in the admin.

Request body

Field	Type	Description
name	string
commission	object or null	The group’s own rates; null = the programme’s. A null rate inherits that channel. (optional, nullable)
customer_discount	object or null	The group’s buyer discount; null = the programme’s. (optional, nullable)
dry_run	boolean	(optional)

Response 201

Returns AffiliateGroupWriteResult.

Field	Type	Description
dry_run	boolean
group	AffiliateGroup
members_detached	integer	Deleting: partners who fall back to the programme’s rates. (optional)
partner_codes_sync_failed	boolean	(optional)

{
  "dry_run": false,
  "group": {
    "id": "id",
    "name": "Gold",
    "commission": {
      "type": "percent",
      "code_rate": 1,
      "link_rate": 1
    },
    "customer_discount": {
      "type": "percentage",
      "value": 1
    },
    "member_count": 1
  },
  "members_detached": 1,
  "partner_codes_sync_failed": false
}

Example

curl -X POST "https://charm.appfleece.app/api/v1/program/affiliates/groups" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Gold"}'

Errors

unauthorized · invalid_token · insufficient_scope · access_required · validation_error · rate_limited · idempotency_conflict

Every error body carries code, message, request_id and a doc_url pointing at the matching entry in the error catalog.