Price a payment run (beta)
Prices a run of payments without writing anything: the lines named (name, amount, currency), or the last run with changes.
Path parameters
orgIdstringRequiredThe opaque organization id issued to you, normally CUID-shaped (for example
cmsx…). It is not anorg_-prefixed alias. Pass it unchanged in every organization-scoped path.
Headers
Idempotency-KeystringOptionalSame semantics as
Idempotency-Keyon the money routes (replay on the same body,409on a different one, released by a4xx), but optional here: without it the request simply runs once with no replay. EveryPOST,PATCHandDELETEhonors it; send one whenever your client might retry.
Body
This endpoint expects a JSON object, or no body.
linesarray of objectOptionalShow 3 properties
namestringOptionalamountstringOptionalcurrencystringOptional
changesarray of objectOptionalShow 2 properties
namestringOptionalamountstringOptional
Behavior
Totals, fees and warnings, as the Avvio assistant estimates. A POST only because the lines are a body; nothing is prepared or sent.
Responses
200The estimate.
Errors
400VALIDATION_ERROR: a query parameter was refused, anderrorsnames it. Alimitoutside its range is refused, not clamped; acursorwe did not issue for this organization is refused (start from the first page); an unknown filter value or a parameter sent twice is refused.401The key was refused. Nothing ran.
UNAUTHORIZED: missing, invalid or revoked, or a key on a route that does not accept one.KEY_EXPIRED: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated.KEY_IP_NOT_ALLOWED: the key is pinned to source addresses and this request came from another.
403A valid key that may not make this write. Nothing was changed.
FORBIDDEN: the key belongs to a different organization.ACCOUNT_BLOCKED: API access for your organization is suspended.LIVE_KEY_ORG_NOT_APPROVED: a live key, before we have approved your business verification. Use a test key until then.INSUFFICIENT_SCOPE: a read-only key. Issue one with thewritescope.
429Too many requests. The default ceiling is 100 requests per minute per API credential on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies.
Obey
Retry-After; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its sameIdempotency-Key.
Error body · Error
typestringRequiredStable machine-readable code.
detailstringRequiredWhat went wrong, in a sentence. Always a string, so
detail.toLowerCase()is safe.More
This is the field to read on
BAD_REQUESTandPROVIDER_REJECTED, where the type alone does not name the condition.messagestringRequiredThe same text as
detail, kept for integrations written beforedetailexisted. Readdetail.resolutionstringOptionalWhat to do about it, when there is a specific answer. It is not on every error (it is absent on
BAD_REQUEST,NOT_FOUND,PAYOUT_NOT_CANCELABLEandDESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back todetail.statusintegerRequiredHTTP status, repeated in the body.
statusCodeintegerRequiredThe same value as
status, kept for integrations written beforestatusexisted. Readstatus.requestIdstringRequiredQuote this to support and we can find the exact request. Also sent as the
x-request-idresponse header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your ownx-request-idon the request and we use it, so your trace and ours share one identifier; otherwise we mint one.errorsarray of stringOptionalPresent on VALIDATION_ERROR; names each field that failed.
originalIdempotencyKeystringOptionalOn
DUPLICATE_REQUEST_DETECTEDonly. Send the request again with this to receive the original payout instead of making a second one. Without it there is no way to recover except by risking a double payment.originalPayoutIdstringOptionalOn
DUPLICATE_REQUEST_DETECTEDonly. The payout the first request created.originalBatchIdstringOptionalOn a batch
DUPLICATE_REQUEST_DETECTED. The run the first request created.originalRequestIdstringOptionalOn a
409 PAYOUT_OUTCOME_UNKNOWNreplay. TherequestIdof the call whose outcome is unknown; quote it to support.existingRecipientIdstringOptionalOn
BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.existingMethodIdstringOptionalOn
BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.limitobjectOptionalOn
PAYOUT_LIMIT_EXCEEDEDfrom a payout. Which cap refused it and what is left of it.Show 8 properties
scopestringRequiredorganization: a cap on your whole organization (seelimitsonGET /policy).api_key: a cap on the key that made the call (apiKeyLimits).Allowed values:organizationapi_keywindowstringRequiredsingleis one payout;dailyandmonthlyare the UTC day and calendar month.Allowed values:singledailymonthlycapUsdstringRequiredusedUsdstring | nullRequiredWhat already counts in this window.
nullforsingle. On the per-end-user cap, that end user's own volume.remainingUsdstring | nullRequiredcapUsd - usedUsd, never below zero: the most a payout may be under this cap right now.nullforsingle.resetsAtstring<date-time> | nullRequiredWhen the window starts over.
nullforsingle.capstringOptionalThe cap's name as the message says it (
single-payout,daily,daily per-end-user,monthly). Prose; branch onscopeandwindow.valueUsdstringOptionalThe same value as
capUsd.
Branch on type, never on the status or the message. Every error type is listed with what to do about it.
Was this page helpful?