Recurring payables

This page shows you how to set up a payable that repeats on a schedule, such as a monthly retainer, and how to manage it over time. A recurring payable is a template plus a schedule. On each occurrence date, Wingspan generates a new payable from the template.

Create a recurring payable

Call POST /v3/payments/recurring-payables with the payee, currency, schedule, and the payable template.

curl -X POST "https://api.wingspan.app/v3/payments/recurring-payables" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "payeeId": "q7Lm2VxR9tKd4WnB8sHc1Z",
    "currency": "USD",
    "externalId": "NW-RETAINER-PRIYA",
    "schedule": {
      "frequency": "Monthly",
      "interval": 1,
      "anchorDate": "2026-10-01",
      "dayOfMonth": 1,
      "timezone": "America/Chicago",
      "businessDayAdjustment": "NextBusinessDay",
      "holidayCalendar": "USFederalReserve",
      "endCondition": { "type": "AfterOccurrences", "maxOccurrences": 12 }
    },
    "payableTemplate": {
      "paymentTermsDays": 15,
      "notes": "Monthly advisory retainer",
      "lineItems": [
        { "description": "Advisory retainer", "type": "Services", "totalCost": 2500.00 }
      ]
    }
  }'

// (trimmed)
{
  "id": "Rp2Xk7Lw4Qz9Tn1Mv6Hb3C",
  "payeeId": "q7Lm2VxR9tKd4WnB8sHc1Z",
  "currency": "USD",
  "nextOccurrenceDate": "2026-10-01",
  "occurrencesGenerated": 0,
  "events": { "createdAt": "2026-09-24T18:00:00Z" }
}

A duplicate externalId returns 409 ResourceConflict. Create is never an upsert.

The schedule

Field	What it does
`frequency`	`Daily`, `Weekly`, `SemiMonthly`, `Monthly`, or `Annual`.
`interval`	"Every N periods". `Monthly` with `interval: 3` is quarterly; `Weekly` with `interval: 2` is every two weeks. Defaults to 1.
`anchorDate`	The first or reference occurrence date. Required with `frequency`. A past anchor only sets the phase; Wingspan never generates past occurrences.
`dayOfWeek`	Required for `Weekly`.
`dayOfMonth`	For `Monthly` and `Annual`. In a shorter month, it falls on the last day of that month.
`daysOfMonth`	For `SemiMonthly` only: exactly two days, such as `[1, 15]`.
`timezone`	IANA timezone that occurrence dates are evaluated in. Can't change after the first occurrence.
`businessDayAdjustment`	`PreviousBusinessDay`, `NextBusinessDay`, or `None` (default). Moves a due date that lands on a non-business day.
`holidayCalendar`	`USFederalReserve` or `None` (default).
`prorationPolicy`	`None` (default) or `ByDays`, for starting, pausing, or cancelling mid-period.
`endCondition`	`{ "type": "OnDate", "endDate": "..." }` or `{ "type": "AfterOccurrences", "maxOccurrences": 1 to 30 }`. `Never` isn't allowed on a recurring payable, because it sends money out.

The template

payableTemplate is the body stamped onto each generated payable:

Field	What it does
`lineItems`	The lines for each payable. On a template, the line type field is `type` (not `lineItemType`).
`paymentTermsDays`	0 to 180. Each generated payable's due date is its issue date plus this many days. If you omit it, it's inherited from the engagement or your payer defaults.
`splits`	Optional splits carried onto each payable.
`notes`, `metadata`	Copied onto each payable.

Statuses and actions

Status	Meaning
`Active`	Generating payables on schedule.
`Paused`	Not generating. The schedule is kept.
`Completed`	The end condition was reached. Final.
`Cancelled`	Stopped for good. Final.

The schema also defines a Draft status.

Action	Endpoint	Effect
Pause	`POST /v3/payments/recurring-payables/{recurringPayableId}/pause`	Stops generating.
Resume	`POST /v3/payments/recurring-payables/{recurringPayableId}/resume`	Back to `Active`, generating forward from now. Occurrences missed while paused are never made up.
Cancel	`POST /v3/payments/recurring-payables/{recurringPayableId}/cancel`	Stops for good. Can't be resumed.
Generate now	`POST /v3/payments/recurring-payables/{recurringPayableId}/generate-now`	Pulls the next occurrence forward, creates its payable immediately (`201`, returns the payable), and moves `nextOccurrenceDate` on.
Delete	`DELETE /v3/payments/recurring-payables/{recurringPayableId}`	Removes the recurring payable. Payables it already generated aren't affected.

An action from the wrong status returns 409.

Preview upcoming occurrences

GET /v3/payments/recurring-payables/{recurringPayableId}/upcoming-occurrences lists future dates without creating anything. Each has occurrenceDate, resolvedDueDate (after business-day and holiday adjustment), and sequenceNumber. Use page[size] to limit how many; page tokens aren't supported here.

Change a recurring payable

PATCH /v3/payments/recurring-payables/{recurringPayableId} changes schedule, payableTemplate, or metadata. It never changes status; use the actions.

payableTemplate merges into the stored template. Omitted template fields stay the same, and null clears a nullable field.
lineItems, when sent, replaces the whole array.
Changes apply to later occurrences, not the next one that's already been computed.

Find generated payables

Each generated payable carries recurringPayableId. The recurring payable tracks occurrencesGenerated, lastOccurrenceDate, and nextOccurrenceDate. Pay generated payables like any other: open and approve them as your process requires, then pay directly or through a payroll run.

List recurring payables with GET /v3/payments/recurring-payables, filtered by filter[payeeId][eq], filter[externalId][eq], or filter[status][eq], and sorted with sort[createdAt]=desc. Repeat the same sort on every page.

Recurring payable webhooks aren't subscribable yet. Read the recurring payable, or watch the generated payables.

Common mistakes

Using lineItemType in the template. Template line items use type.
Expecting a resumed schedule to catch up. Resume only generates forward.
Using Never as the end condition. A recurring payable needs OnDate or AfterOccurrences.
Assuming generated payables pay themselves. They're new payables. Make sure your approval and payroll process picks them up.