Skip to main content
POST
Mark a payout batch as paid

Purpose

Record a batch as paid when you paid the vendor outside PuppetVendors.

When to use

When a batch failed and you settled it another way, for example by bank transfer. 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 payout transactions

Next step

Get a payout (poll the update)

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 request you intend to make. Same key and the same body while the first request is still processing: 409 IDEMPOTENCY_IN_PROGRESS. Same key and a different body: 422 IDEMPOTENCY_KEY_REUSED. A new key is a new request.

Required string length: 8 - 128

Path Parameters

batchId
string
required

The legacy batch id (a random 10-char string, not an ObjectId)

Required string length: 1 - 64

Body

application/json
markAsPaidMethod
string
required

How the batch was settled (free text, e.g. bankTransfer)

Maximum string length: 120
Example:

"bankTransfer"

markAsPaidComments
string
required

Recorded with the batch; legacy requires both fields

Maximum string length: 2000
Example:

"paid by wire on 2026-03-02"

Response

Mark-paid accepted; executing asynchronously. Poll GET /payouts/make-payment/{transactionId} for the latest status.

success
boolean
data
object