Skip to main content
POST
Create a payout

Purpose

Pay line items and adjustments to one or more vendors.

When to use

After a successful preview. The payout runs in the background. You get a transactionId to poll. Send one Idempotency-Key per payout. Part of the Pay vendors with the API flow. Same key and the same body:
  • Still processing: 409 IDEMPOTENCY_IN_PROGRESS. Poll details.transactionId.
  • After the run finishes: 200 with replay: true and the current status. status moves from processing to completed once the background job finishes, usually 30 to 60 seconds after the first call. transactionId, dryRun, vendors and totalPayout match the first response. Nothing is paid twice.
Same key and a different body: 422 IDEMPOTENCY_KEY_REUSED. Use a new key. Read status from the response you get. Retry code must accept either 202 or 200 and read status from the body. For the latest status, call Get a payout (GET /payouts/make-payment/{id}).

Request and response

The parameters, request body, code examples (curl and other languages) and a full response example are shown below this section. They are generated from the OpenAPI spec. A finished replay is 200. The body has these fields:

Errors

Every error has the shape {"success": false, "error": {"code", "message", "errorId", "details"}}. Branch on error.code.

Previous step

Preview a payout

Next step

Get a payout

Authorizations

x-access-token
string
header
required

JWT minted from a merchant API key (mk_live_…) by POST /authenticate. Send the token value directly, with no "Bearer" prefix. Tokens last 14 days and can be renewed at POST /refresh-token; revoking the key refuses the next request made with any token minted from it.

Headers

Idempotency-Key
string
required

Required. A unique string you choose, 8–128 characters (a UUID works). Use one key per payout you intend to make. Same key and the same body while the first request is still processing: 409 IDEMPOTENCY_IN_PROGRESS. Same key and the same body after the run finishes: 200 with replay: true and the current status. status moves from processing to completed once the background job finishes, usually 30 to 60 seconds after the first call. The replay has the same transactionId, dryRun, vendors and totalPayout as the first response, and nothing is paid twice. Read status from the response you get. For the latest status, call GET /payouts/make-payment/{transactionId}. Same key and a different body: 422 IDEMPOTENCY_KEY_REUSED. A new key is a new payout.

Required string length: 8 - 128

Body

application/json
vendors
object[]
required

The vendors to pay, one group each, paid as one batch per vendor. A vendorId may appear only once, and a line item or adjustment id under only one vendor (ids compare case-insensitively). Every vendor must belong to this shop and be ready for the method, or the whole request is refused and nothing is paid.

Required array length: 1 - 50 elements
method
enum<string>
required

READ-side method name, one for every vendor of the run; mapped to legacy resolver keys at the bridge. manual records a payment made outside the app and needs manualMethod

Available options:
stripe,
paypal,
globalPayouts,
manual
manualMethod
enum<string>

How a manual payout was made, the same options as the merchant portal. Required when method is manual, refused with any other method. Shown in the vendor email. A manual payout's payoutMethod is other.

Available options:
bankTransfer,
paypal,
cash,
other
Example:

"bankTransfer"

notifyVendor
boolean
default:true

Whether the run emails the vendor

payoutDate

Recorded as the payout date. Either an RFC 3339 date-time or a calendar date without a time (YYYY-MM-DD), recorded as that day in the merchant portal's MM/DD/YYYY. When omitted, defaults to today in the shop's timezone (as MM/DD/YYYY), as the merchant portal pre-fills it

Example:

"2026-03-02"

comment
string

Free-text note recorded with the run

Maximum string length: 2000

Response

Same Idempotency-Key and the same body, after the run has finished. replay is true. status is the current status. It moves from processing to completed once the background job finishes, usually 30 to 60 seconds after the first call. transactionId, dryRun, vendors and totalPayout match the first response. Nothing is paid twice. Read status here, or call GET /payouts/make-payment/{transactionId} for the latest status.

success
boolean
data
object