--- title: "Settle campaign participant" method: POST path: "/v1/creator-campaigns/{campaignId}/participants/{participantId}/settle" tags: ["Creator Campaigns"] --- # Settle campaign participant `POST /v1/creator-campaigns/{campaignId}/participants/{participantId}/settle` ## Request - Base URL: `https://zernio.com/api` - URL: `https://zernio.com/api/v1/creator-campaigns/{campaignId}/participants/{participantId}/settle` - Auth: HTTP bearer Records a payout of the participant's payable balance and fires `campaign_payout.settled`. Omit `amountCents` to settle the whole payable balance. An amount above it answers 400, and nothing payable answers 409. Send an `Idempotency-Key` so a retry never records the payout twice. ### Settlement modes - `none` settlement: records a payout you made elsewhere. - `external` settlement: pay from your own rails when `campaign_payout.payable` fires, then call this with your payout id in `externalReference` (required in this mode). - `treasury` settlement: transfers the amount from your Zernio balance to the creator's connected Stripe account, then records it with the Stripe transfer id as `externalReference`. ### Treasury payouts The transfer fee (4%, $0.50 minimum) is added on top: the creator receives the full amount and your balance is debited `totalCents`. - The creator must have finished payout setup from their campaign page (409 otherwise). - A balance that does not cover the amount plus the fee answers 402. - Money from a card top-up charged under 7 days ago cannot be paid out yet: a payout that needs it answers 409 `payout_funds_locked` with the day it can be sent. Set `recordOnly: true` to record a payout you made yourself instead of moving money through the treasury (the webhook then carries `recorded: true`). A treasury payout needs an owner, admin or billing admin, signed in or through a full-access key they created (403 otherwise). Recording with `recordOnly` does not. #### While Stripe confirms the transfer The amount sits in the participant's `settling` balance; a reject in that window cannot reverse it. - If Stripe refuses the transfer, the amount returns to payable. - If Stripe does not answer, the amount stays in `settling`. The next settle call for this participant finishes that payout first (even with nothing payable left). #### Conflicts (409) - A retry asking for a different `amountCents` than the payout in progress answers 409 with the amount in progress. - A settle while another request is still waiting on Stripe for the same payout answers 409 ("This payout is being sent to Stripe right now. Try again in a minute."). - A payout Stripe has not confirmed after 24 hours answers 409 ("This payout is being confirmed with Stripe. Try again after the next reconciliation (within 24 hours).") until the daily reconciliation finishes it: settled if Stripe made the transfer, returned to payable if it did not. - A creator held by an unfinished payout batch answers 409 ("This creator is in a card payout that is not finished yet."). ## Path parameters - `campaignId` string, required - `participantId` string, required ## Headers - `Idempotency-Key` string ## Request body - object - `amountCents` integer: Defaults to the whole payable balance. - `externalReference` string: Your payout id. Required when the campaign settles externally. - `recordOnly` boolean: Treasury campaigns only: record a payout you already made outside Zernio, without moving money. Ignored on other settlement modes, which always record. ## Response `201` Settlement recorded - object - `settlement` CampaignSettlement, required - `entryId` string, required: The ledger settlement entry. - `participantId` string, required - `amountCents` integer, required - `externalReference` string, nullable, required - `payableCents` integer, required: Payable balance left after this settlement. - `settledAt` string, date-time, required - `transferId` string: Treasury settlement only: the Zernio transfer that moved the money. The creator receives amountCents in full. - `feeCents` integer: Treasury settlement only: the transfer fee, added on top of amountCents. - `totalCents` integer: Treasury settlement only: debited from your balance, amountCents plus feeCents. ## Other responses - `400`: Invalid request - `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired. - `402`: Your Zernio balance does not cover the amount plus the fee on top (code `payment_required`). Top up and retry. - `403`: Refused. Code `feature_not_available`: creator campaigns run on usage-based billing and the workspace that owns the campaign is not on it yet ("Creator campaigns require usage-based billing..."; contact support to switch), or the campaign reached `caps.maxParticipants` (invites and joins only). Code `insufficient_permissions`: a restricted API key without the `creator_campaigns` resource group. - `404`: The campaign, participant or submission does not exist, belongs to another team, or sits in a profile this key cannot reach (code `resource_not_found`). - `409`: The campaign, participant or submission is not in a state that allows this action (code `invalid_resource_state`); the message names the current state. Also returned while the same `Idempotency-Key` is still processing. - `422`: Idempotency-Key reused with a different request - `502`: Stripe did not confirm the transfer (code `temporarily_unavailable`). Retry the settle call: the transfer is not made twice within Stripe's 24-hour idempotency window; after that, retries answer 409 until the daily reconciliation settles the payout or returns it to payable. ## Changes - **2026-10-28** `8f2c44dd7550`: 1 info - endpoint added [Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/creator-campaigns/:campaignId/participants/:participantId/settle/post.md) --- [API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/c319eb5d95b6?raw)