---
title: "Apply a customer workflow transition to an AP item"
method: POST
path: "/companies/{companyId}/ap/{id}/transitions"
tags: ["AR/AP"]
---

# Apply a customer workflow transition to an AP item

`POST /companies/{companyId}/ap/{id}/transitions`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/companies/{companyId}/ap/{id}/transitions`
- Auth: HTTP bearer

DARK — 404s unless company_subledger_flags.ar_ap_items_enabled is true. Workflow-only customer state machine (Wave 2, Option A); no money moves and no journal entry is posted. `scheduled` records a payment-intent date (requires scheduledPayDate); `unscheduled` cancels that intent; `recorded_paid` is a fail-closed reflection of an already-applied bank match that covers the bill (requires matchedTransactionId) and never touches the reconciled transaction. The response echoes the updated item plus its recomputed availableTransitions.

## Request body

- object
  - `to` 'scheduled' | 'unscheduled' | 'recorded_paid' | 'void', required
  - `scheduledPayDate` string, date: Required when to=scheduled (YYYY-MM-DD).
  - `matchedTransactionId` string, uuid: Required when to=recorded_paid.
  - `reason` string, nullable: Optional reason; recorded on void (terminal cancellation) and recorded_paid.

## Response `200`

Transition applied; returns the AP item (with availableTransitions). `void` is a terminal cancellation delegating to the FSM void edge (open/partially_paid/paid → void); no money moves and the customer is offered no re-open target.

## Other responses

- `403`: Insufficient role for this company/entity
- `404`: Not found, or AR/AP not enabled for this company
- `409`: AP_ITEM_STATE_CHANGED — the item moved to a different state before the transition could be applied (optimistic-concurrency conflict).
- `422`: Validation or business-rule failure — VALIDATION_ERROR, BUSINESS_RULE_VIOLATION, ILLEGAL_AP_TRANSITION, or ILLEGAL_AP_PAY_STATE_TRANSITION.

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)