Pay vendors with the API

Purpose

This guide pays one vendor with the API, from start to finish. Each step is one request you can copy.

Before you start

You need a merchant API key (mk_live_…).
Automated Payouts must be off. If it is on, payout requests return 409 AUTOMATED_PAYOUTS_ACTIVE. Turn it off in Settings > Payouts > Automated Payouts > Disable Automated Payouts.
Set these shell variables:

export PV=https://production-api.puppetvendors.com
export PV_API_KEY=mk_live_your_key
export VENDOR_ID=your_vendor_id

Step 1. Authenticate

TOKEN=$(curl -s -X POST $PV/authenticate \
  -H "Content-Type: application/json" \
  -d "{\"apiKey\": \"$PV_API_KEY\"}" | jq -r .data.token)

Send the token in the x-access-token header on every request below. Reference: Authenticate.

Step 2. Create a payout adjustment (optional)

Skip this step if you only pay order line items.

curl -s -X POST $PV/payouts/adjustments \
  -H "x-access-token: $TOKEN" -H "Content-Type: application/json" \
  -d "{\"vendorId\": \"$VENDOR_ID\", \"amount\": 25.50, \"type\": \"ADDITION\", \"comments\": \"March bonus\"}"

Save data._id as ADJ_ID. Reference: Create a payout adjustment.

Step 3. List pending payouts

curl -s "$PV/payouts/pending?vendorId=$VENDOR_ID&startDate=2026-01-01&endDate=2026-12-31" \
  -H "x-access-token: $TOKEN"

Each vendor shows its unpaid total. Reference: List pending payouts.

Step 4. List the vendor’s pending items

curl -s "$PV/payouts/pending/items/$VENDOR_ID?startDate=2026-01-01&endDate=2026-12-31" \
  -H "x-access-token: $TOKEN"

Collect the lineItemIds and adjustmentIds to pay. Reference: List a vendor’s pending items.

Step 5. Preview the payout

curl -s -X POST $PV/payouts/make-payment/dry-run \
  -H "x-access-token: $TOKEN" -H "Content-Type: application/json" \
  -d "{\"vendors\": [{\"vendorId\": \"$VENDOR_ID\", \"adjustmentIds\": [\"$ADJ_ID\"]}],
       \"method\": \"manual\", \"manualMethod\": \"other\", \"notifyVendor\": false}"

200 OK

{
  "success": true,
  "data": {
    "dryRun": true,
    "vendors": [
      { "vendorId": "6a956f90bffa472b6babe773", "vendorName": "Acme Goods", "totalAmount": 25.5, "totalLineItemsCount": 1, "issue": null }
    ],
    "totalPayout": 25.5
  }
}

Fix any vendor with a non-null issue before you pay. Reference: Preview a payout.

Step 6. Create the payout

Send the same body with a new Idempotency-Key.

Same key, same body, while the run is still processing: 409 IDEMPOTENCY_IN_PROGRESS. Poll details.transactionId.
Same key, 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. transactionId, dryRun, vendors and totalPayout match the first response. Nothing is paid twice.
Same key, different body: 422 IDEMPOTENCY_KEY_REUSED. Use a new key.

Read status from the response you get. For the latest status, call GET /payouts/make-payment/{id}.

KEY=$(uuidgen)
curl -s -X POST $PV/payouts/make-payment \
  -H "x-access-token: $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "{\"vendors\": [{\"vendorId\": \"$VENDOR_ID\", \"adjustmentIds\": [\"$ADJ_ID\"]}],
       \"method\": \"manual\", \"manualMethod\": \"other\", \"comment\": \"March payouts\", \"notifyVendor\": false}"

The first response is 202 Accepted with data.transactionId and status: "processing". Save transactionId as TXN_ID. A replay after the run finishes looks like this:

200 OK

{
  "success": true,
  "data": {
    "requestId": "6adc216010794278e53fed32",
    "status": "completed",
    "replay": true,
    "transactionId": "YSR66PQUCL",
    "dryRun": false,
    "vendors": [
      { "vendorId": "6a956f90bffa472b6babe773", "vendorName": "Acme Goods", "totalAmount": 25.5, "totalLineItemsCount": 1, "issue": null }
    ],
    "totalPayout": 25.5
  }
}

Reference: Create a payout.

Step 7. Poll the payout

Poll every 2–5 seconds until status is completed or failed.

curl -s $PV/payouts/make-payment/$TXN_ID -H "x-access-token: $TOKEN"

200 OK

{
  "success": true,
  "data": {
    "transactionId": "YSR66PQUCL",
    "requestId": "6adc216010794278e53fed32",
    "operation": "make-payment",
    "batchId": null,
    "status": "completed",
    "payoutMethod": "other",
    "comment": "March payouts",
    "hadIssue": false,
    "batches": [
      {
        "batchId": "FB2XIEVDP0",
        "vendorId": "6a956f90bffa472b6babe773",
        "vendorName": "Acme Goods",
        "amount": 25.5,
        "status": "paid",
        "reason": null,
        "gatewayRef": null,
        "markAsPaid": { "marked": true }
      }
    ],
    "canRetry": false
  }
}

Reference: Get a payout.

Step 8. Check the transaction list

curl -s "$PV/payouts/transactions?limit=10" -H "x-access-token: $TOKEN"

Your payout is listed once, with payoutMethod, comment and its batches. markAsPaid has marked only.

{
  "transactionId": "YSR66PQUCL",
  "payoutMethod": "other",
  "comment": "March payouts",
  "batches": [
    { "batchId": "FB2XIEVDP0", "status": "paid", "markAsPaid": { "marked": true } }
  ]
}

Reference: List payout transactions.

Step 9. If a batch failed

If a batch has status: "failed", do one of these:

Retry it: Retry a payout batch.
Or, if you paid the vendor another way, record it: Mark a batch as paid.

Both need an Idempotency-Key and return a transactionId you poll as in step 7.

Status values

Object	Values
Payout `status`	`processing`, `completed`, `failed`
Batch `status`	`pending`, `paid`, `failed`, `cancelled`

Next step

Create a payout has every field and error in full.

Getting Started

Authentication

Guides

Vendors

Users

Payouts

Payout Adjustments

Products

Purpose

Before you start

Step 1. Authenticate

Step 2. Create a payout adjustment (optional)

Step 3. List pending payouts

Step 4. List the vendor’s pending items

Step 5. Preview the payout

Step 6. Create the payout

Step 7. Poll the payout

Step 8. Check the transaction list

Step 9. If a batch failed

Status values

Next step

​Purpose

​Before you start

​Step 1. Authenticate

​Step 2. Create a payout adjustment (optional)

​Step 3. List pending payouts

​Step 4. List the vendor’s pending items

​Step 5. Preview the payout

​Step 6. Create the payout

​Step 7. Poll the payout

​Step 8. Check the transaction list

​Step 9. If a batch failed

​Status values

​Next step

Purpose

Before you start

Step 1. Authenticate

Step 2. Create a payout adjustment (optional)

Step 3. List pending payouts

Step 4. List the vendor’s pending items

Step 5. Preview the payout

Step 6. Create the payout

Step 7. Poll the payout

Step 8. Check the transaction list

Step 9. If a batch failed

Status values

Next step