Create a payout batch

Submit up to 1,000 payouts as one run.

POSTCopy URL: https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/payouts/batches

POST/payments/organizations/{orgId}/payouts/batches

Open in explorer

curl

IDEMPOTENCY_KEY=$(uuidgen)  # new key per call; reuse it only to retry this exact request
curl -s -X POST "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/payouts/batches" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "externalReferenceId": "<externalReferenceId>",
        "items": "<items>"
      }'

Node

const idempotencyKey = crypto.randomUUID(); // new key per call; reuse it only to retry this exact request

const res = await fetch(`${process.env.AVVIO_BASE_URL}/payments/organizations/${process.env.AVVIO_ORG_ID}/payouts/batches`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
    'Idempotency-Key': idempotencyKey,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    "externalReferenceId": "<externalReferenceId>",
    "items": "<items>"
  }),
});
console.log(res.status, await res.json());

Python

import os
import uuid
import requests

idempotency_key = str(uuid.uuid4())  # new key per call; reuse it only to retry this exact request

res = requests.post(
    f"{os.environ['AVVIO_BASE_URL']}/payments/organizations/{os.environ['AVVIO_ORG_ID']}/payouts/batches",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
        "Idempotency-Key": idempotency_key,
    },
    json={
        "externalReferenceId": "<externalReferenceId>",
        "items": "<items>"
    },
)
print(res.status_code, res.json())

Try it

202AcceptedResponse status202 Accepted400 Bad Request401 Unauthorized403 Forbidden409 Conflict429 Too Many Requests500 Internal Server Error

{
  "batchId": "cmf3k2xg00009q8b7v0w2x4yz",
  "externalReferenceId": "payroll-2026-09-01",
  "status": "received",
  "autoCommit": true,
  "counts": {
    "received": 250,
    "invalid": 0,
    "validated": 0,
    "creating": 0,
    "created": 0,
    "create_failed": 0,
    "canceled": 0,
    "requires_review": 0
  },
  "estimatedSourceTotal": null,
  "createdAt": "2026-09-01T14:03:11.000Z",
  "updatedAt": "2026-09-01T14:03:11.000Z",
  "completedAt": null
}

Path parameters

• orgIdstringRequired

  The opaque organization id issued to you, normally CUID-shaped (for example cmsx…). It is not an org_-prefixed alias. Pass it unchanged in every organization-scoped path.

Headers

• Idempotency-KeystringRequired

  A unique value per logical operation, 1-255 chars of A-Z a-z 0-9 _ . : -.

  More

  Reuse it to retry. Same key with the same body replays the stored response; same key with a different body is a 409, because answering with the first call's result would hand you a receipt for a payout you did not request. A 4xx releases the key, so you can fix the body and reuse it.

  Reuse it; do not generate one per attempt. A key minted per attempt defeats replay entirely: every retry looks like a new request, so every retry pays. We also watch for an identical body arriving under a different key within 15 minutes and refuse it with DUPLICATE_REQUEST_DETECTED.

  Records are kept for 7 days. That is a retention window only: there is no path where an expired key is re-executed.

• X-Allow-DuplicatestringOptional

  Set to true to send a request that is byte-identical to one you sent within the last 15 minutes under a different key. true is the only accepted value. It switches off the guard that catches a retry arriving under a fresh key, so send it only when you mean to pay twice.

Body

This endpoint expects a JSON object.

• externalReferenceIdstringRequired

  Your own run id (a payroll file name, a cycle id). Required, and unique per organization: a second batch with the same id answers 409 PAYOUT_BATCH_DUPLICATE_REFERENCE naming the original, and nothing is submitted. The Idempotency-Key protects this HTTP attempt for 7 days; the run id protects the payroll run forever, including a re-run under a fresh key. A corrected resubmission is a new run and needs its own id (for example payroll-2026-09-01-r2). Echoed back and filterable on the batch list.

• autoCommitbooleanOptionalDefaults to true

  True: a run with zero validation errors proceeds straight to creation. False, or any errors found: the batch holds at awaiting_confirmation for your review.

• itemsarray of objectRequired

  The payout instructions, in order.

  Show 8 properties

  • amountstringRequired

    How much, as a decimal string. What you send by default; what the recipient receives, in their currency, when amountLeg is destination.

  • destinationAccountIdstringRequired

    The recipient's method.destinationAccountId from the registration response (the account that call registered), or the one you stored for it.

  • amountLegstringOptionalDefaults to "source"

    Which side of the payout amount describes.

    More

    source takes every fee out of what you sent, so the recipient receives less than the figure you named.

    destination pays them that figure exactly, in their currency, and adds the fees to your debit instead. Naming 3400 MXN on a live corridor debited 201.879397 USDC and paid out 3400.00.

    source_net keeps the figure in your currency but means it the same way: "send them $200 worth". We convert at the market rate published by GET /rates and lock that destination, so the fees land on your debit. Naming 200 USD on a live corridor paid out 3426.81 MXN and debited 203.447236: the fees, plus the difference between the market rate we quoted you and the rate the network executed at.

    The two locking modes need capabilities.exactOutput on the corridors call; elsewhere they are refused with EXACT_OUTPUT_UNSUPPORTED rather than quietly pricing the other side.

    Allowed values:sourcedestinationsource_net
  • expectDestinationstringOptional

    What you told the payer they would receive. Omit it and you send at whatever the market did between quoting and sending.

  • maxDriftBpsintegerOptionalDefaults to 200

    Tolerated drift in basis points. Defaults to 200 (2%). Only read when expectDestination is set; ignored otherwise.

  • referencestringOptional

    Your payment reference. Echoed back and searchable.

  • purposeOfPaymentstringOptional

    Corridor-defined payment purpose, from GET /payment-reasons. Required for payouts to INR, GHS, CNY and BRL; validated against the catalog whenever you send it; never defaulted.

  • endUserobjectOptional

    Your own customer this payout is sent for: the party sending through your platform, never the recipient. In payroll the employer is the end user and the worker is the recipient; omit the object when you are the sender yourself. Attribution and the per-end-user daily cap key on id; it is not forwarded to the payment network and does not change the sender of record, which stays your organization. Echoed on the payout and in every webhook, so a support question is answerable without your own id map.

    Show 3 properties

    • idstringOptional

      Your stable identifier for the sending customer (not the recipient).

    • namestringOptional

      Person's display or legal name.

    • emailstring<email>Optional

      Person's email address in standard email format.

Behavior

Mass payouts. Each line of items is exactly a POST /payouts body; the batch validates every line first (nothing is priced or debited), then turns the valid lines into ordinary payouts.

202 means received, not paid: poll GET .../batches/{batchId} or subscribe to the payout_batch.* webhooks. With autoCommit: true (the default) a run with zero validation errors proceeds straight to creation. When your organization requires approvals, autoCommit is forced to false (and echoed back as false) so the run waits for POST .../confirm. If any line fails validation, or autoCommit is false, the batch holds at awaiting_confirmation: read GET .../batches/{batchId}/items?status=invalid, then either POST .../confirm to proceed with the valid lines or POST .../cancel to stop the run.

The batch tracks creation. Once a line is created it carries a payoutId and that payout lives the ordinary payout lifecycle: payout.* webhooks, GET /orders/{payoutId}, the event feed. A batch that reads completed is a run whose every line was resolved, not a claim that the money has settled.

The Idempotency-Key covers the run. A submit loop that dies and resubmits the same file under the same key gets the same batch back, never a second payroll. A 500 PAYOUT_OUTCOME_UNKNOWN means the run may exist: list batches by externalReferenceId before submitting again, and never under a new key.

Batch submission has its own rate limit: 30 per minute.

Responses

202The batch, in received. Nothing has been validated yet, let alone paid. A replayed idempotent request returns the original and sets the Idempotency-Replayed response header.

Headers

• Idempotency-Replayedboolean

Body · PayoutBatch

• batchIdstringRequired
• externalReferenceIdstring | nullRequired

  Your own run id, echoed back.

• statusstringRequired

  A batch moves received -> validating -> either creating (autoCommit, zero errors) or awaiting_confirmation (anything else) -> creating -> completed. canceled is reachable until creation starts; failed means the run broke, not a line. The batch tracks creation; payouts settle on their own lifecycle afterwards.

  Allowed values:receivedvalidatingawaiting_confirmationcreating

  Show 3 more values

  completedcanceledfailed
• autoCommitbooleanRequired
• countsobjectRequired

  Lines by status. The values sum to the number of lines submitted.

  Show 8 properties

  • receivedintegerRequired
  • invalidintegerRequired
  • validatedintegerRequired
  • creatingintegerRequired
  • createdintegerRequired
  • create_failedintegerRequired
  • canceledintegerRequired
  • requires_reviewintegerRequired
• estimatedSourceTotalstring | nullRequired

  Advisory. What the valid lines will draw from your balance, set when validation finishes; null while validation is running and when any line locks the destination side (no rate is consulted at validation time). Compare against GET /balance before confirming. Half a paid payroll is worse than none.

• errorobjectOptional

  Present only when status is failed, with the run-level reason.

• createdAtstring<date-time>Required
• updatedAtstring<date-time>Required
• completedAtstring<date-time> | nullRequired

Errors

• 400

  Validation of the envelope itself (a malformed line, too many lines, a bad externalReferenceId), or a missing or malformed Idempotency-Key (IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID).

• 401

  The 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.
• 403

  A valid key that may not make this write. Nothing was changed.

  • MASS_PAYOUTS_DISABLED: batch submission is off for your organization. GET /policy lists mass_payouts in features when it is on; contact support to enable it.
  • FORBIDDEN, ACCOUNT_BLOCKED, LIVE_KEY_ORG_NOT_APPROVED, INSUFFICIENT_SCOPE: as on every write (ForbiddenWrite).
• 409

  PAYOUT_BATCH_DUPLICATE_REFERENCE: a batch with this externalReferenceId already exists. The run id is unique per organization, which is the guard against a submit job that crashed and re-ran with a fresh key. originalBatchId names the existing run; nothing was submitted. Or an idempotency conflict (IDEMPOTENCY_KEY_CONFLICT, IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS, PAYOUT_OUTCOME_UNKNOWN on a replay, DUPLICATE_REQUEST_DETECTED; see MoneyIdempotencyConflict).

• 429

  Too 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 same Idempotency-Key.

• 500

  PAYOUT_OUTCOME_UNKNOWN: the call failed after the money may have moved, and we cannot yet say whether it did. Do not retry with a new Idempotency-Key; that is how a payment goes out twice. Look the outcome up first (the operation says where), or replay the same key, which answers 409 PAYOUT_OUTCOME_UNKNOWN until we resolve it. Send support the requestId.

  Every other 500 is INTERNAL: nothing was recorded under the key, and retrying with the same key is safe.

Error body · Error

• typestringRequired

  Stable machine-readable code.

• detailstringRequired

  What went wrong, in a sentence. Always a string, so detail.toLowerCase() is safe.

  More

  This is the field to read on BAD_REQUEST and PROVIDER_REJECTED, where the type alone does not name the condition.

• messagestringRequired

  The same text as detail, kept for integrations written before detail existed. Read detail.

• resolutionstringOptional

  What 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_CANCELABLE and DESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back to detail.

• statusintegerRequired

  HTTP status, repeated in the body.

• statusCodeintegerRequired

  The same value as status, kept for integrations written before status existed. Read status.

• requestIdstringRequired

  Quote this to support and we can find the exact request. Also sent as the x-request-id response header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your own x-request-id on the request and we use it, so your trace and ours share one identifier; otherwise we mint one.

• errorsarray of stringOptional

  Present on VALIDATION_ERROR; names each field that failed.

• originalIdempotencyKeystringOptional

  On DUPLICATE_REQUEST_DETECTED only. 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.

• originalPayoutIdstringOptional

  On DUPLICATE_REQUEST_DETECTED only. The payout the first request created.

• originalBatchIdstringOptional

  On a batch DUPLICATE_REQUEST_DETECTED. The run the first request created.

• originalRequestIdstringOptional

  On a 409 PAYOUT_OUTCOME_UNKNOWN replay. The requestId of the call whose outcome is unknown; quote it to support.

• existingRecipientIdstringOptional

  On BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.

• existingMethodIdstringOptional

  On BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.

Branch on type, never on the status or the message. Every error type is listed with what to do about it.

Avvio Partner Payouts · Payout batches · operation createPayoutBatch

Try it: Create a payout batch

POST https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/payouts/batches

API key Required

Test keys only. Sent as x-api-key through this site's proxy to the Avvio API, never saved, and cleared when you close this dialog.

orgId pathRequired

Idempotency-Key headerRequired

X-Allow-Duplicate headerOptional

Body JSON{ "externalReferenceId": "<externalReferenceId>", "items": "<items>" }

Send request