Record a payment made to a partner

POST /program/affiliates/{affiliate_id}/payouts


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_record_partner_payout`

Charm never sends money: the merchant pays the partner themselves, then this records it as the admin’s Record payment does. The payable commission through through turns paid, an open payment request closes, and the partner gets a confirmation e-mail unless notify_partner: false. Call with dry_run: true for the amount, ask the merchant to confirm they already paid exactly that, then repeat with confirm_paid: true plus expected_amount and expected_currency from the preview; a balance that moved since is refused.

Parameters

Name	In	Type	Description
`affiliate_id`	path	string	The partner’s `id` from `GET /program/affiliates/payouts/due`.

Request body

Field	Type	Description
`through`	string	Pay commission payable through this day, YYYY-MM-DD; default today. (optional)
`reference`	string	The merchant’s payment reference, e.g. the bank transfer id. (optional)
`note`	string	(optional)
`notify_partner`	boolean	E-mail the partner a confirmation; default true. (optional)
`expected_amount`	number	The `amount` from the dry run. (optional)
`expected_currency`	string	The `currency` from the dry run. (optional)
`confirm_paid`	boolean	The merchant confirmed the money has already been paid. (optional)
`dry_run`	boolean	Preview only: validate, resolve references and return the `diff` and `summary`, but write nothing. Costs no idempotency key and is limited as a read. Call with this first, show the merchant, then repeat without it. (optional)

Response `201`

Returns PartnerPayoutResult.

Field	Type	Description
`dry_run`	boolean
`recorded`	boolean
`payout_id`	string or null	(nullable)
`partner`	PayoutPartner
`through`	string
`amount`	number
`currency`	string or null	(nullable)
`commissions`	integer
`notify_partner`	boolean
`payment_request`	PartnerPaymentRequest or null	(nullable)

{
  "dry_run": false,
  "recorded": false,
  "payout_id": "payout id",
  "partner": {
    "id": "id",
    "name": "Gold",
    "email": "shopper@example.com",
    "code": "code",
    "status": "active"
  },
  "through": "through",
  "amount": 1,
  "currency": "EUR",
  "commissions": 1,
  "notify_partner": false,
  "payment_request": {
    "amount": 1,
    "currency": "EUR",
    "requested_at": "2026-10-01T09:30:00.000Z",
    "payment_details": {}
  }
}

Example

# 1. Dry run: writes nothing and needs no Idempotency-Key. Show the merchant the result.
curl -X POST "https://charm.appfleece.app/api/v1/program/affiliates/<affiliate_id>/payouts" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"dry_run":true}'

# 2. After the merchant says yes: the real call with the confirmation.
curl -X POST "https://charm.appfleece.app/api/v1/program/affiliates/<affiliate_id>/payouts" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"expected_amount":1,"expected_currency":"EUR","confirm_paid":true}'

Errors

unauthorized · invalid_token · insufficient_scope · access_required · not_found · 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.