curl --request POST \
  --url https://app.sideshift.app/api/embed/accounts/transfer/batch \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "transfers": [
    {
      "toAccountId": "acct_user1",
      "amountCents": 5000,
      "idempotencyKey": "payout-user1-2026-04",
      "metadata": {
        "obligationType": "campaign",
        "obligationReference": "contract-user1",
        "description": "Approved April payout for completed content",
        "approvalReference": "approval-user1",
        "programId": "campaign-april"
      }
    },
    {
      "toAccountId": "acct_user2",
      "amountCents": 7500,
      "idempotencyKey": "payout-user2-2026-04",
      "metadata": {
        "obligationType": "campaign",
        "obligationReference": "contract-user2",
        "description": "Approved April payout for completed content",
        "approvalReference": "approval-user2",
        "programId": "campaign-april"
      }
    },
    {
      "toAccountId": "acct_user3",
      "amountCents": 3000,
      "idempotencyKey": "payout-user3-2026-04",
      "metadata": {
        "obligationType": "campaign",
        "obligationReference": "contract-user3",
        "description": "Approved April payout for completed content",
        "approvalReference": "approval-user3",
        "programId": "campaign-april"
      }
    }
  ]
}
'

{
  "success": true,
  "data": {
    "totalCount": 3,
    "successCount": 2,
    "failureCount": 1,
    "results": [
      {
        "index": 0,
        "success": true,
        "data": {
          "transferId": "txfr_abc123",
          "fromAccountId": "company",
          "toAccountId": "acct_user1",
          "amountCents": 5000,
          "amountUsd": 50,
          "status": "completed",
          "direction": "company_to_user",
          "destinationBalance": "withdrawal",
          "createdAt": "2026-04-03T12:00:00.000Z"
        }
      },
      {
        "index": 1,
        "success": true,
        "data": {
          "transferId": "txfr_def456",
          "fromAccountId": "company",
          "toAccountId": "acct_user2",
          "amountCents": 7500,
          "amountUsd": 75,
          "status": "completed",
          "direction": "company_to_user",
          "destinationBalance": "withdrawal",
          "createdAt": "2026-04-03T12:00:01.000Z"
        }
      },
      {
        "index": 2,
        "success": false,
        "error": {
          "code": "AMOUNT_TOO_LARGE",
          "message": "Amount too large. Maximum is $1000.00",
          "details": {
            "requestedAmountCents": 128394,
            "maximumAmountCents": 100000,
            "configuredMaximumAmountCents": 100000,
            "systemMaximumAmountCents": 10000000
          }
        }
      }
    ]
  }
}

Batch transfer

Process multiple transfers in a single request. Transfers are executed sequentially — use this instead of sending many parallel single-transfer requests.

Each transfer in the array supports the same parameters as the single transfer endpoint.

Best-effort (default): omit atomic or set atomic: false. Results are returned per-transfer; a failure in one item does not stop the others.

Atomic: set atomic: true when every transfer must commit, or none should. SideShift validates the whole batch (accounts, amounts, commercial evidence, and combined source balances) before moving money. If any item would fail, the API returns an error and executes nothing. If an item fails after money has started moving, remaining items are not attempted and already-settled items are reversed. A successful atomic batch returns the same per-item result envelope with failureCount: 0 and atomic: true.

Retry an aborted atomic batch with new per-item idempotencyKey values (and a new batch idempotencyKey if you sent one). Replaying the same keys returns the stored abort and does not pay again.

Why batch? Sending 50+ parallel requests to /accounts/transfer causes Firestore transaction contention on the source wallet, resulting in INTERNAL_ERROR failures. The batch endpoint eliminates this by processing transfers one at a time within a single HTTP call.

Limits: Maximum 200 transfers per batch.

Idempotency and evidence: Every transfer requires its own idempotencyKey. Live batch items also require the same commercial-evidence metadata as the single-transfer endpoint. Atomic batches also reject duplicate per-item keys.

POST

accounts

transfer

batch

curl --request POST \
  --url https://app.sideshift.app/api/embed/accounts/transfer/batch \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "transfers": [
    {
      "toAccountId": "acct_user1",
      "amountCents": 5000,
      "idempotencyKey": "payout-user1-2026-04",
      "metadata": {
        "obligationType": "campaign",
        "obligationReference": "contract-user1",
        "description": "Approved April payout for completed content",
        "approvalReference": "approval-user1",
        "programId": "campaign-april"
      }
    },
    {
      "toAccountId": "acct_user2",
      "amountCents": 7500,
      "idempotencyKey": "payout-user2-2026-04",
      "metadata": {
        "obligationType": "campaign",
        "obligationReference": "contract-user2",
        "description": "Approved April payout for completed content",
        "approvalReference": "approval-user2",
        "programId": "campaign-april"
      }
    },
    {
      "toAccountId": "acct_user3",
      "amountCents": 3000,
      "idempotencyKey": "payout-user3-2026-04",
      "metadata": {
        "obligationType": "campaign",
        "obligationReference": "contract-user3",
        "description": "Approved April payout for completed content",
        "approvalReference": "approval-user3",
        "programId": "campaign-april"
      }
    }
  ]
}
'

{
  "success": true,
  "data": {
    "totalCount": 3,
    "successCount": 2,
    "failureCount": 1,
    "results": [
      {
        "index": 0,
        "success": true,
        "data": {
          "transferId": "txfr_abc123",
          "fromAccountId": "company",
          "toAccountId": "acct_user1",
          "amountCents": 5000,
          "amountUsd": 50,
          "status": "completed",
          "direction": "company_to_user",
          "destinationBalance": "withdrawal",
          "createdAt": "2026-04-03T12:00:00.000Z"
        }
      },
      {
        "index": 1,
        "success": true,
        "data": {
          "transferId": "txfr_def456",
          "fromAccountId": "company",
          "toAccountId": "acct_user2",
          "amountCents": 7500,
          "amountUsd": 75,
          "status": "completed",
          "direction": "company_to_user",
          "destinationBalance": "withdrawal",
          "createdAt": "2026-04-03T12:00:01.000Z"
        }
      },
      {
        "index": 2,
        "success": false,
        "error": {
          "code": "AMOUNT_TOO_LARGE",
          "message": "Amount too large. Maximum is $1000.00",
          "details": {
            "requestedAmountCents": 128394,
            "maximumAmountCents": 100000,
            "configuredMaximumAmountCents": 100000,
            "systemMaximumAmountCents": 10000000
          }
        }
      }
    ]
  }
}

Authorizations

x-api-key

string

header

required

Your SideShift Connect API key (sk_live_* or sk_test_*). Generate from Settings → Connect.

Body

application/json

transfers

object[]

required

Maximum array length: 200

Show child attributes

atomic

boolean

default:false

When true, the batch is all-or-nothing. Default false keeps best-effort per-item results.

idempotencyKey

string

Optional batch-level key for atomic retries. If omitted, SideShift derives one from the per-item keys.

Minimum string length: 8

Response

Batch completed. Best-effort batches may still contain per-item failures; atomic batches only return 200 when every item committed.

success

boolean

data

object

Show child attributes