Commission payloads
Commission events deliver a CommissionFatPayload (a commission_transaction object) as data.object. The same shape is sent for every commission event - field values change with the transaction's type and status.
Every webhook is wrapped in the standard envelope:
Code
Commission fields
| Field | Type | Nullable | Notes |
|---|---|---|---|
object | string | No | Always "commission_transaction". |
id | string | No | Commission UUID, ct_-prefixed. |
type | string | No | commission_payment, refund_commission_adjustment, or refund_commission_reversal. |
status | string | No | See status enum below. |
amount | string (decimal) | No | Commission amount, decimal string (e.g. "445.00"). |
fee | string (decimal) | No | Fee withheld, decimal string (e.g. "0" or "7.741935483870968"). |
net | string (decimal) | No | Net after fee. Can be negative on refunds (e.g. "-7.741935483870968"). |
currency | string | No | Lowercase currency code (e.g. usd). |
refund_adjustment | string (decimal) | Yes | Refund amount applied; null on reversals. |
commission_rate | float | No | Commission percentage (e.g. 5.0, 10.0). |
sale_id | string | Yes | Source sale UUID, sl_-prefixed. |
team_member | object | Yes | team_member (Variant A - carries user_id/roles). null on commission.reversed. See team_member. |
installment | object | Yes | Installment record, when the commission is tied to an installment. |
payout | object | No | See payout. |
idempotency_key | string | Yes | e.g. transfer_{sale_id}_{member_id}, adjustment_..., reversal_.... |
created | datetime | No | ISO 8601 creation timestamp. |
updated | datetime | No | ISO 8601 last-update timestamp. |
These are the wire keys you receive. The emitter renames the internal/long-form field names to the short wire keys: transaction_type → type, net_amount → net, and platform_fee → fee. The emitted JSON always uses the short keys type, net, and fee shown above.
amount, fee, and net are decimal strings in major currency units with 2 decimal places (e.g. "445.00") - not integer cents. Always parse them with a decimal type (never a float, to avoid rounding error).
The commission object's created and updated are ISO 8601 datetime strings (e.g. "2026-06-20T12:12:42.745Z"), matching the envelope's created_at and the other payload entities. Parse them as timestamps, not integers.
Status enum
The following status values are the complete set emitted for commission transactions: pending, merchant_outstanding, completed, failed, withheld, cancelled.
| Status | Seen with |
|---|---|
pending | commission.reversed |
merchant_outstanding | commission.created, commission.paid |
completed | commission.refunded source commission |
failed | commission.failed |
withheld | commission.refunded |
cancelled | commission.cancelled |
commission.created
Fired when a commission transaction is generated (typically alongside sale.paid). type is commission_payment, status is merchant_outstanding, and team_member carries the Variant A shape {user_id, roles}.
Full commission.created payload
Code
commission.paid
Fired when a commission is marked paid. Same commission_transaction shape as commission.created; check payout.transfer_id and payout.date for settlement details.
commission.refunded
Fired when a refund reduces a commission. type is refund_commission_adjustment, refund_adjustment is set, and net is negative.
Full commission.refunded payload
Code
commission.reversed
Fired when a commission is reversed. type is refund_commission_reversal, status is pending, refund_adjustment is null, and team_member is null.
Full commission.reversed payload
Code
On commission.reversed, team_member is null. Always guard against a missing team_member when handling reversals.
commission.cancelled
Fired when a commission is cancelled. type is commission_payment, status is cancelled, team_member is populated, and the payout fields are all null.
Full commission.cancelled payload
Code
commission.failed
Fired when a commission payout attempt fails. Same commission_transaction shape; inspect status and payout for the failure context.
commission.updated
Fired when an existing commission transaction is modified. Same commission_transaction shape; compare created and updated to see when the change occurred.
In all commission contexts, team_member (when present) carries the Variant A shape {object, id, user_id, first_name, last_name, email, roles} - it includes user_id but not department/is_active. This differs intentionally from the Variant B shape used in sale/refund contexts. See team_member.