REreacherapp
Campaigns

Settle a creator payment

Changed on

Triggers a real Stripe transfer + wallet debit when reward_type='cash'. reward_type='custom' records the settlement only — no money moves. Idempotency-Key is REQUIRED and the inner PaymentService.settle runs claim/release semantics so a retry with the same key can never double-pay. Every successful settlement emits an audit.campaigns.settle log line for on-call reconciliation. X-Dry-Run: true skips the Stripe call entirely. Payout controls can refuse a cash settlement before money moves: 423 PAYOUTS_FROZEN (payouts paused for the shop), 409 PAYOUT_LIMIT_EXCEEDED (per-transfer or 24-hour cap), 503 PAYOUT_CONTROLS_UNREADABLE. All three are temporary; retrying with the same Idempotency-Key is judged again. A key bound to a sub-user settles only if that user is an admin (403 PAYOUT_ROLE_FORBIDDEN). A cash settle for a shop in a region Reacher can't pay creators in is refused with 409 PAYOUT_RAIL_MANUAL; the brand pays outside Reacher and marks it paid in the dashboard.

post/campaigns/payments/settle

Request

  • Base URL
    https://api.reacherapp.com/public/v1
  • URL
    https://api.reacherapp.com/public/v1/campaigns/payments/settle
  • Auth
    API key in header x-api-key and API key in header x-shop-id

Headers

Idempotency-Keystring nullable
X-Dry-Runstring nullable

Request body

creator_idinteger required
campaign_idinteger required
amountnumber required

Settlement amount in the campaign's currency. Capped at $100,000 per call as a sanity guard.

currencystring required

ISO 4217 currency code (e.g. 'USD'). Informational — the shop's persisted wallet currency takes precedence at settlement time. If the wallet currency differs from this value, the transfer executes in the wallet currency without rejection. The response's currency field confirms the currency actually used for the transfer.

reward_typestring required

'cash' triggers a Stripe transfer + wallet debit; 'custom' records the settlement only (no money moves).

campaign_creator_mapping_idinteger required

REQUIRED. The campaign-creator mapping id that the settlement is being recorded against. The portal surfaces this id on every creator row in GET /campaigns/{id}/detail and in the response to the accept endpoint, so callers always have it. Required because the underlying PaymentService.settle only runs its double-payment guard (claim_for_settlement_sync) when a mapping id is present — omitting it would leave the money-moving path with idempotency-only protection (a different Idempotency-Key per call could debit the wallet repeatedly with no DB-level guard).

metadataobject nullable

Free-form metadata stored alongside the settlement (e.g. agent annotation, internal reference).

Response

Successful Response

successboolean required
transfer_idstring nullable

Stripe transfer id for cash settlements. Null for custom-reward settlements (no Stripe call).

amountnumber nullable
currencystring nullable
paid_atstring nullable
wallet_balancenumber nullable

Remaining wallet balance after the settlement.

Changes

  • 2840b044a7daRevision changes
    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

  • 291230805105Revision changes
    • info

      api operation id settle_payment_campaigns_payments_settle_post removed and replaced with campaign_payments_settle