Payouts

Push 2 to 50 USD payouts in one atomic batch from your prefunded Glide treasury, with idempotency keys, per-item execution ids and exact replay semantics.

POST https://glide.co/api/partner/treasury/transfers/batch

One call moves USD from your prefunded Glide treasury into your users’ personal Glide balances. The whole batch is a single synchronous database transaction. There is no queue, no provider call inside the transaction, and no partial success.

The treasury model

Glide binds your partner record to exactly one business entity, one accounting owner, one entity-scoped USD balance, one external payer UUID and one reserve account. That binding is immutable once made. It does not create a business, approve it, or supply funds.

You prefund the treasury by settling real USD into the bound reserve account, then a Glide operator records the settlement against evidence. Funding is an operator attestation of already-settled external money, not a deposit API you can call.

Settlement through this endpoint means spendable personal Glide USD credit. It does not mean a bank withdrawal or an on-chain transfer. Both sides of each payout are completed transfer records with zero fee: a debit on your treasury and a credit on the user. The user’s copy shows as incoming and is labelled Payout from partner in their transaction history.

Requirements

Requirement	Where it comes from
treasury:write on your token	A Glide admin enables it on your token entitlements
An active treasury with an unexpired mandate	Glide binds, funds and activates it
A pre-creation receipt for each recipient	Your own POST /api/partner/users call
payouts:receive and transfers:read on each recipient’s grant	The user’s consent screen
Each recipient’s account is active	The user

This endpoint adds no verification, wallet, receiving-account or webhook gate of its own. A recipient with no verification can still be paid. Your token does not also need the read or receive scopes to call this endpoint, though you do need them to read the results back.

Request

Headers:

Header	Value
Authorization	Bearer <token> carrying treasury:write
Content-Type	application/json
Idempotency-Key	1 to 128 characters from [A-Za-z0-9._:-], required

{
  "payer_entity_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "currency": "USD",
  "items": [
    { "execution_id": "11111111-1111-4111-8111-111111111111", "payout_id": "22222222-2222-4222-8222-222222222222", "user_id": "33333333-3333-4333-8333-333333333333", "amount_cents": "2500", "reference": "invoice-104" },
    { "execution_id": "44444444-4444-4444-8444-444444444444", "payout_id": "55555555-5555-4555-8555-555555555555", "user_id": "66666666-6666-4666-8666-666666666666", "amount_cents": "4000", "reference": "invoice-105" }
  ]
}

Field	Rule
payer_entity_id	UUID. Must equal your binding’s external payer id. It cannot select another balance
currency	Exactly "USD"
items	2 to 50 entries. Every object is strict and rejects unknown fields
items[].execution_id	UUID, unique within the request. Your idempotency unit for one payment attempt
items[].payout_id	UUID, unique within the request. Your obligation identifier
items[].user_id	UUID of the recipient
items[].amount_cents	Positive integer string. No sign, decimals, exponent, whitespace or leading zero
items[].reference	1 to 200 characters

UUIDs are canonicalized to lowercase. Individual amounts and the request total must each be at most 9007199254740991. The streamed body limit is 64 KiB, which comfortably fits 50 items.

The same user may appear more than once in a batch, as long as each entry is a distinct obligation with its own execution_id and payout_id.

Choosing ids

execution_id identifies one attempt to move a specific amount to a specific user. Generate it once, store it next to the obligation in your database, and reuse it on every retry. payout_id identifies the obligation itself. Neither is generated by Glide, and neither should be regenerated because a call failed.

Never mint a fresh execution_id to “retry” a payment. A new id is a new payment. Retrying with the ids you already stored is what makes a lost response safe.

Response

HTTP 200, including on replay, with one result per requested item in request order.

{
  "batch_id": "77777777-7777-4777-8777-777777777777",
  "treasury_entity_id": "88888888-8888-4888-8888-888888888888",
  "currency": "USD",
  "total_amount_cents": "6500",
  "items": [
    { "execution_id": "11111111-1111-4111-8111-111111111111", "user_id": "33333333-3333-4333-8333-333333333333", "transfer_id": "99999999-9999-4999-8999-999999999999", "amount_cents": "2500", "state": "processed", "version": 1, "fee_cents": "0", "fee_included": false },
    { "execution_id": "44444444-4444-4444-8444-444444444444", "user_id": "66666666-6666-4666-8666-666666666666", "transfer_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "amount_cents": "4000", "state": "processed", "version": 1, "fee_cents": "0", "fee_included": false }
  ]
}

Field	Notes
transfer_id	The user’s credit transaction id. Store it against your payout
state	Always processed. There is no partial or pending state
version	Always 1
fee_cents	Always "0"
fee_included	Always false
total_amount_cents	Includes reused items, so it can exceed the money actually debited by this call

transfer_id is the correlation key for everything downstream. It appears in GET /api/partner/users/:id/transfers and in the transfer.settled webhook.

Atomicity

The executor locks your partner mapping, treasury, relationship receipts, users and grant rows, validates the entity and balance binding, then credits recipients in a deterministic order. A revocation, suspension or configuration change either lands before execution or waits until the already-authorized transaction commits.

The success audit, batch response, receipts, treasury debit, user credits, paired transactions, activity entry and webhook outbox all commit together. If the audit or the outbox fails, the entire new batch rolls back. You will never receive a successful subset.

Caps and policy

Under the treasury lock, Glide enforces the caps an operator configured with you:

Cap	Applies to
Per item	A single item’s amount
Per batch	The sum of new items in this request
Rolling 24 hours	New amount moved in the trailing day
Lifetime	New amount moved since binding
Transfers per hour	Count of new transfers
Transfers per 24 hours	Count of new transfers

Only new transfers consume amount or count allowance, so replays are free. Hitting a cap exactly is allowed. A cap error names the limit it violated without revealing how much allowance you have left.

Caps must increase from per item through per batch and rolling 24 hours to lifetime. If a step-up amount is configured and an item exceeds it, this release denies the batch with policy_denied. There is no approval token that bypasses it. Ask Glide to raise the cap instead.

New executions additionally require an active treasury, an unexpired mandate, accepted owner membership in the active business entity, and verified funding. The debit itself is guarded by available_balance >= new_total, so an underfunded batch fails rather than overdrawing.

Idempotency and replay

Situation	Result
Same key and canonical request	Original stored response. No new money, receipt, usage or event
Same key and a changed request, including reordered items	409 idempotency_conflict
Different key, identical previously executed item	Reuses that item’s transfer_id. Only unseen executions are debited
Reused execution_id with a changed recipient, payer, payout_id, amount, currency or reference	409 execution_conflict. No item in the batch executes
Validation, policy or funds rejection	Rejection is audited. No settled batch is stored and no execution ids are consumed
Commit succeeded but you lost the response	Retry the same key and payload to recover the original body
Timeout or any uncertain outcome	Keep the execution ids and retry. Do not manufacture replacements

An unconfirmed call is not a failed call. On a timeout, a dropped connection, a 5xx or an unparseable response, resend the identical body with the identical Idempotency-Key. A replayed 200 reconciles you against the transfers that already exist.

Replay still requires current partner authentication, receipt membership, active users and both current consents. Treasury suspension or an expired mandate stops new money movement while leaving an authorized replay available. A batch made entirely of reused items needs no new mandate and consumes no policy allowance.

Revoking a user’s access can stop you reading a historical receipt. It does not reverse the payment. A later failure of the user’s own bank withdrawal cannot change your completed treasury transfer either.

Errors

Rate limit is 10 requests per minute per partner, with Retry-After: 60 on a 429.

{ "error": { "code": "insufficient_funds", "message": "Treasury balance is insufficient for this batch", "request_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" } }

HTTP	Codes
400	invalid_request, invalid_json
401	invalid_token, with WWW-Authenticate: Bearer
403	grant_required, partner_inactive, user_inactive, treasury_inactive, payer_not_allowed, policy_denied
404	user_not_found, treasury_not_configured
409	idempotency_conflict, execution_conflict, insufficient_funds
413	body_too_large
429	rate_limited
500	internal_error
503	auth_unavailable, audit_unavailable

See Errors for what to do about each one.

After settlement

The user’s credit lands in their personal Glide USD balance immediately, visible under Glide balance in the Glide app. From there the user, not you, drives the cash-out:

1. Convert USD to USDC in Glide, reviewing the quoted fees. This step requires approved verification.
2. Continue to a bank withdrawal from the conversion receipt, or open the bank flow directly against available USDC.

Held balances are unchanged by your payout. A withdrawal that later fails restores the user’s own funds and never touches your completed payout receipt.

Treasury operations

These are Glide-side operations. Ask Glide to perform them; they are not partner-callable.

Ask Glide to	What happens
Bind your treasury	Supplies your entity, external payer id, reserve account, caps and mandate expiry, and creates an empty USD balance in disabled status
Configure policy	Sets per-item, per-batch, rolling 24 hour and lifetime caps, transfer counts, mandate expiry and an optional step-up amount. Each edit bumps a policy version and audits the before and after values
Record funding	Attests settled external USD against evidence, credits the balance and writes an immutable funding receipt
Set treasury status	active, suspended or disabled. Activation requires a valid binding, a future mandate, an active partner and verified funding
Report on the treasury	Returns configuration, available and held cents, rolling and lifetime usage, and recent funding receipts
List batches and transfers	Pages your batch history and per-batch items, including reused executions

Binding cannot silently adopt existing funds, and funding receipts are immutable. Corrections need an explicit accounting operation rather than an edit. Treasury suspension leaves your reads and webhook delivery working and only stops new payouts. Partner suspension stops everything.