> ## Documentation Index
> Fetch the complete documentation index at: https://dev.puppetvendors.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pay vendors with the API

> Pay vendors end to end: authenticate, add an adjustment, preview, pay, poll and check the result.

## 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:

```bash theme={null}
export PV=https://production-api.puppetvendors.com
export PV_API_KEY=mk_live_your_key
export VENDOR_ID=your_vendor_id
```

## Step 1. Authenticate

```bash theme={null}
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](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/authenticate.md).

## Step 2. Create a payout adjustment (optional)

Skip this step if you only pay order line items.

```bash theme={null}
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](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/create-payout-adjustment.md).

## Step 3. List pending payouts

```bash theme={null}
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](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/list-pending-payouts.md).

## Step 4. List the vendor's pending items

```bash theme={null}
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](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/list-pending-payout-items.md).

## Step 5. Preview the payout

```bash theme={null}
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}"
```

```json 200 OK theme={null}
{
  "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](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/dry-run-payout.md).

## 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}`.

```bash theme={null}
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:

```json 200 OK theme={null}
{
  "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](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/make-payout-payment.md).

## Step 7. Poll the payout

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

```bash theme={null}
curl -s $PV/payouts/make-payment/$TXN_ID -H "x-access-token: $TOKEN"
```

```json 200 OK theme={null}
{
  "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](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/get-payout-run.md).

## Step 8. Check the transaction list

```bash theme={null}
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.

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

Reference: [List payout transactions](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/list-payout-transactions.md).

## Step 9. If a batch failed

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

* Retry it: [Retry a payout batch](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/retry-payout-batch.md).
* Or, if you paid the vendor another way, record it: [Mark a batch as paid](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/mark-payout-batch-paid.md).

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](https://dev.puppetvendors.com/api-reference/v2/merchant/endpoint/make-payout-payment.md) has every field and error in full.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.