curl --request POST \
--url https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-access-token: <api-key>' \
--data '
{
"markAsPaidMethod": "bankTransfer",
"markAsPaidComments": "paid by wire on 2026-03-02"
}
'import requests
url = "https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid"
payload = {
"markAsPaidMethod": "bankTransfer",
"markAsPaidComments": "paid by wire on 2026-03-02"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"x-access-token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'x-access-token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
markAsPaidMethod: 'bankTransfer',
markAsPaidComments: 'paid by wire on 2026-03-02'
})
};
fetch('https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'markAsPaidMethod' => 'bankTransfer',
'markAsPaidComments' => 'paid by wire on 2026-03-02'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"x-access-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid"
payload := strings.NewReader("{\n \"markAsPaidMethod\": \"bankTransfer\",\n \"markAsPaidComments\": \"paid by wire on 2026-03-02\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("x-access-token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-access-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"markAsPaidMethod\": \"bankTransfer\",\n \"markAsPaidComments\": \"paid by wire on 2026-03-02\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-access-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"markAsPaidMethod\": \"bankTransfer\",\n \"markAsPaidComments\": \"paid by wire on 2026-03-02\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"requestId": "<string>",
"transactionId": "<string>",
"status": "processing",
"dryRun": false
}
}{
"success": false,
"error": {
"message": "Resource not found",
"code": "NOT_FOUND",
"errorId": "err_1783365360839_j281w7b",
"details": {}
}
}{
"success": false,
"error": {
"message": "Resource not found",
"code": "NOT_FOUND",
"errorId": "err_1783365360839_j281w7b",
"details": {}
}
}{
"success": false,
"error": {
"message": "Resource not found",
"code": "NOT_FOUND",
"errorId": "err_1783365360839_j281w7b",
"details": {}
}
}{
"success": false,
"error": {
"message": "Resource not found",
"code": "NOT_FOUND",
"errorId": "err_1783365360839_j281w7b",
"details": {}
}
}{
"success": false,
"error": {
"code": "AUTOMATED_PAYOUTS_ACTIVE",
"message": "This store pays vendors automatically, so payouts cannot also be made through the API. To pay through the API, go to Settings > Payouts > Automated Payouts and select \"Disable Automated Payouts\".",
"errorId": "err_1792776147401_4vdjdqw"
}
}{
"success": false,
"error": {
"message": "Resource not found",
"code": "NOT_FOUND",
"errorId": "err_1783365360839_j281w7b",
"details": {}
}
}Mark a payout batch as paid
Mark a payout batch as paid when it was settled outside PuppetVendors. Runs asynchronously.
Not available while Automated Payouts is on: returns 409 AUTOMATED_PAYOUTS_ACTIVE.
Idempotency: send an Idempotency-Key header. 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.
curl --request POST \
--url https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-access-token: <api-key>' \
--data '
{
"markAsPaidMethod": "bankTransfer",
"markAsPaidComments": "paid by wire on 2026-03-02"
}
'import requests
url = "https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid"
payload = {
"markAsPaidMethod": "bankTransfer",
"markAsPaidComments": "paid by wire on 2026-03-02"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"x-access-token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'x-access-token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
markAsPaidMethod: 'bankTransfer',
markAsPaidComments: 'paid by wire on 2026-03-02'
})
};
fetch('https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'markAsPaidMethod' => 'bankTransfer',
'markAsPaidComments' => 'paid by wire on 2026-03-02'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"x-access-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid"
payload := strings.NewReader("{\n \"markAsPaidMethod\": \"bankTransfer\",\n \"markAsPaidComments\": \"paid by wire on 2026-03-02\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("x-access-token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-access-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"markAsPaidMethod\": \"bankTransfer\",\n \"markAsPaidComments\": \"paid by wire on 2026-03-02\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://production-api.puppetvendors.com/payouts/batches/{batchId}/mark-paid")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-access-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"markAsPaidMethod\": \"bankTransfer\",\n \"markAsPaidComments\": \"paid by wire on 2026-03-02\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"requestId": "<string>",
"transactionId": "<string>",
"status": "processing",
"dryRun": false
}
}{
"success": false,
"error": {
"message": "Resource not found",
"code": "NOT_FOUND",
"errorId": "err_1783365360839_j281w7b",
"details": {}
}
}{
"success": false,
"error": {
"message": "Resource not found",
"code": "NOT_FOUND",
"errorId": "err_1783365360839_j281w7b",
"details": {}
}
}{
"success": false,
"error": {
"message": "Resource not found",
"code": "NOT_FOUND",
"errorId": "err_1783365360839_j281w7b",
"details": {}
}
}{
"success": false,
"error": {
"message": "Resource not found",
"code": "NOT_FOUND",
"errorId": "err_1783365360839_j281w7b",
"details": {}
}
}{
"success": false,
"error": {
"code": "AUTOMATED_PAYOUTS_ACTIVE",
"message": "This store pays vendors automatically, so payouts cannot also be made through the API. To pay through the API, go to Settings > Payouts > Automated Payouts and select \"Disable Automated Payouts\".",
"errorId": "err_1792776147401_4vdjdqw"
}
}{
"success": false,
"error": {
"message": "Resource not found",
"code": "NOT_FOUND",
"errorId": "err_1783365360839_j281w7b",
"details": {}
}
}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.
| Status | Code | Meaning | Fix |
|---|---|---|---|
| 400 | VALIDATION_ERROR | Idempotency-Key header missing or not 8–128 characters. | Send a unique key, e.g. a UUID. |
| 400 | VALIDATION_ERROR | A parameter or body field is missing or invalid. error.details names the field. | Fix the field and resend. |
| 404 | NOT_FOUND | The resource does not exist in your store. | Check the id. |
| 409 | AUTOMATED_PAYOUTS_ACTIVE | Your store pays vendors automatically. | Settings > Payouts > Automated Payouts > Disable Automated Payouts. Nothing was started. |
| 409 | IDEMPOTENCY_IN_PROGRESS | A request with this key is still processing. | Poll details.transactionId instead of resending. |
| 422 | IDEMPOTENCY_KEY_REUSED | This key was used with a different body. | Use a new key for a new request. |
| 422 | see error.code | The batch is not in a state that allows this (for example it is already paid). | Get the payout to see the batch status. |
| 401 | UNAUTHORIZED | Token missing, invalid or expired. | Call POST /authenticate again and resend. |
| 403 | FORBIDDEN | The token belongs to a vendor key. | Use a merchant API key (mk_live_…). |
Previous step
List payout transactionsNext step
Get a payout (poll the update)Authorizations
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
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.
8 - 128Path Parameters
Body
Was this page helpful?