# Prepare a payment run

> Prepares a run from approved invoices, by id or by rules. Invoices that can't be paid are left out, each with a reason in `skipped`. The run waits for a person to approve it in StrideHQ; no key can approve, fund or pay. `Idempotency-Key` is required.

```
POST https://api.sandbox.stridehq.ai/v1/payment_runs
```


Scope: `payment_runs:prepare`

## Headers

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | string | Yes | A unique value, such as a UUID. The same key and body within 24 hours returns the original response. |

## Body

| Name | Type | Required | Description |
|---|---|---|---|
| `invoice_ids` | array of string | No | Approved invoices to include, up to 200. |
| `due_within_days` | integer | No | Rule. Invoices due on or before this many days from today (0 to 365). An invoice with no due date counts as due today. |
| `include_overdue` | boolean | No | Rule. Include invoices past their due date. Default true. |
| `currency` | string | No | Rule. Only invoices paid in this currency (ISO 4217). |
| `limit_amount` | integer | No | Rule. Invoices are added oldest due date first until the next would go over this total, in minor units. Needs `currency` when the invoices are in more than one. |
| `notes` | string | No | Shown to the approver. Up to 500 characters. |
| `metadata` | object | No | Up to 20 string keys (up to 40 characters) and values (up to 500 characters), for your use. StrideHQ never reads them. Send null to clear it. |

## Responses

- **201**: The run, `pending_approval`, with the invoices that were left out in `skipped`.
- **400**: `unknown_field`, `invalid_parameter`, `idempotency_key_required`, `invalid_json` or `invalid_content_type`.
- **401**: `missing_api_key`, `invalid_api_key`, `revoked_api_key` or `wrong_environment`.
- **403**: `organisation_inactive`.
- **409**: `invoice_already_in_run`, `idempotency_key_reused` or `idempotency_key_in_use`.
- **422**: `nothing_to_pay` (every invoice was skipped; the list is in `error.skipped`) or `own_account_required`.
- **429**: `rate_limited`. Wait for `Retry-After` seconds.

```json
{
  "id": "run_3e5a7c9b1d2f4a6c8e0b2d4f6a8c0e1d",
  "object": "payment_run",
  "reference": "PR-BRIGHT-26-014",
  "status": "pending_approval",
  "created_by_type": "api",
  "invoice_ids": [
    "inv_4b1e7d2a9c3f4e5d8a6b0c1d2e3f4a5b"
  ],
  "skipped": [
    {
      "invoice_id": "inv_0a2c4e6b8d1f4a3c5e7b9d0f2a4c6e8b",
      "code": "bank_details_missing",
      "message": "The creator hasn't added bank details."
    }
  ],
  "funding_currency": "GBP",
  "totals": [
    {
      "currency": "GBP",
      "amount": 250000
    }
  ],
  "subtotal": 250000,
  "fee_rate": "2.50",
  "transaction_fee": 6250,
  "international_payment_fee": 0,
  "total_amount": 256250,
  "amount_received": 0,
  "amount_outstanding": 256250,
  "approved_by": null,
  "approved_at": null,
  "approval_url": "https://app.stridehq.ai/payments/runs?tab=runs",
  "notes": "Weekly creator payments",
  "metadata": {},
  "created_at": "2026-10-29T09:00:00Z",
  "updated_at": "2026-10-29T09:00:00Z"
}
```