redeem_credits
MOVES MONEY: cash out a user's credits as a Stripe transfer to a connected account. Deducts amount credits and pays amount × the credit type's exchange_rate (USD per credit; the rate cannot be overridden). The credit type must be redeemable (else 400 NOT_REDEEMABLE). destination must be this user's own account from onboard_payout_account (else 400 INVALID_DESTINATION). Pass idempotency_key: a retry with the same key returns the first result (idempotent_replay: true) and never deducts or pays twice; without one, reference_id is the key, and with neither every call redeems again. 502 PAYOUT_PENDING means Stripe's answer was lost: retry with the SAME key (idempotency_key in the error) to finish it — if nobody retries, the reconciliation sweep settles it after ~15 minutes (paid, or credits returned only if Stripe definitely refused); a claim it cannot settle safely is flagged for manual review. Errors: 400 INSUFFICIENT_CREDITS, 400 PAYOUT_TOO_SMALL, 404 USER_NOT_FOUND, 402 STRIPE_TRANSFER_FAILED (credits restored), 409 IDEMPOTENCY_KEY_REUSED. Costs 1 CRD (platform credit) per call, charged even when the call is then rejected (a 429 RATE_LIMITED costs nothing). Error results include request_id; quote it to support.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Credits to redeem | |
| reason | No | Reason, shown on the transfer and ledger | |
| api_key | No | Cred API key (optional if set via the x-api-key header) | |
| user_id | No | External user ID | |
| currency | No | Payout currency (default usd) | |
| metadata | No | String key/values added to the Stripe transfer metadata | |
| project_id | No | Cred project ID (optional; the API key already identifies the project) | |
| user_email | No | User email (alternative) | |
| destination | Yes | Stripe connected account ID (acct_…) that receives the payout | |
| reference_id | No | Your reference, stored on the transfer and ledger | |
| x402_payment | No | Base64 x402 PaymentPayload, only when a previous call failed with an x402 PaymentRequired because the account is out of CRD | |
| credit_type_id | Yes | Redeemable credit type | |
| idempotency_key | No | Unique key for this redemption (max 255 chars). Retrying with the same key and same arguments returns the first result instead of repeating it; reusing it for different arguments fails with 409 IDEMPOTENCY_KEY_REUSED. Generate a fresh key (e.g. a UUID) per intended operation and reuse it only to retry that operation. |