curl --request POST \
--url https://production-api.puppetvendors.com/payouts/batches/{batchId}/retry \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-access-token: <api-key>'import requests
url = "https://production-api.puppetvendors.com/payouts/batches/{batchId}/retry"
headers = {
"Idempotency-Key": "<idempotency-key>",
"x-access-token": "<api-key>"
}
response = requests.post(url, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Idempotency-Key': '<idempotency-key>', 'x-access-token': '<api-key>'}
};
fetch('https://production-api.puppetvendors.com/payouts/batches/{batchId}/retry', 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}/retry",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://production-api.puppetvendors.com/payouts/batches/{batchId}/retry"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("x-access-token", "<api-key>")
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}/retry")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-access-token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://production-api.puppetvendors.com/payouts/batches/{batchId}/retry")
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>'
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": {}
}
}Retry a payout batch
Retry a payout batch that was rejected. Runs asynchronously; poll the transaction for the result.
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}/retry \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-access-token: <api-key>'import requests
url = "https://production-api.puppetvendors.com/payouts/batches/{batchId}/retry"
headers = {
"Idempotency-Key": "<idempotency-key>",
"x-access-token": "<api-key>"
}
response = requests.post(url, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Idempotency-Key': '<idempotency-key>', 'x-access-token': '<api-key>'}
};
fetch('https://production-api.puppetvendors.com/payouts/batches/{batchId}/retry', 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}/retry",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://production-api.puppetvendors.com/payouts/batches/{batchId}/retry"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("x-access-token", "<api-key>")
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}/retry")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-access-token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://production-api.puppetvendors.com/payouts/batches/{batchId}/retry")
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>'
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
Retry a failed payout batch.When to use
When Get a payout shows a batch withstatus: failed and canRetry: true. 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. |
| 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 retry)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
Was this page helpful?