Skip to main content
POST
Preview a payout

Purpose

Preview a payout without paying anything.

When to use

Always, right before Create a payout. It runs the same checks, so a preview that succeeds will not fail for a store-level reason. Part of the Pay vendors with the API flow.

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.

Errors

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

Previous step

List a vendor’s pending items

Next step

Create 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.

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

The computation a make-payment run would perform, without writing anything

success
boolean
data
object