Lifecycle and states

Key concept

A receivable is an accounting record of debt (or of its modification). The system does not automatically link incoming movements to specific receivables (when a client has multiple pending invoices, it cannot infer which one is being paid). Transitions to PAID are always the integrator's decision.

States

State	Meaning	How it is reached
PENDING	Active receivable, awaiting collection	Initial state on creation
PAID	Marked as paid by the integrator	PATCH /v1/receivables/{id}/status { "status": "PAID" }
EXPIRED	dueDate passed without being collected	Nightly job, or manual PATCH
SETTLED	The settlement cycle marked this receivable as accounting-closed	Settlement job
DISABLED	Cancelled or invalidated	DELETE /v1/receivables/{id}

Transition diagram

Matching and settlement

Two cycles affect a receivable: matching (the integrator's decision to mark a receivable as PAID via PATCH /v1/receivables/{id}/status) and settlement (an automatic process that closes a receivable as SETTLED when moving the money to the customer's MAIN). Matching is optional; settlement always happens. Differences between collected and invoiced amounts are reflected in the settlement summary, not on individual receivables. See Settlements.

Listing by state

It is very common to filter receivables by state to visualize pending ones:

GET /v1/receivables?receivableAccountId=4242&status=PENDING

For nightly reconciliation, list the ones settled today:

GET /v1/receivables?status=SETTLED&fromDate=2026-05-15T00:00:00-03:00&toDate=2026-05-15T23:59:59-03:00

The fromDate/toDate filters follow the standard filters convention (receivable creation date). To narrow down by state-change date (e.g. when the receivable was marked SETTLED), cross-reference the listing with the account's last settlement window (GET /v1/receivable-accounts/{id}/settlements?fromDate=...). For business dates of the document, use fromIssueDate/toIssueDate or fromDueDate/toDueDate (see Listing filters).

Status modification

Endpoint

PATCH /v1/receivables/{id}/status
Idempotency-Key: ...
Content-Type: application/json

{
  "status": "PAID"
}

Target status	Allowed from	Restriction
PAID	PENDING, EXPIRED	The integrator takes responsibility for matching
EXPIRED	PENDING	No additional restriction, typically done by the nightly job
DISABLED	PENDING, PAID, EXPIRED	Only if not yet settled. Marks the receivable as cancelled in history.

SETTLED and DISABLED are final states and accept no further transitions. Attempting to modify them returns 422 updating-receivable-final-status.

No rollback from PAID/EXPIRED to PENDING

The API does not accept rolling a receivable back from PAID or EXPIRED to PENDING. If you marked it as PAID by mistake and it has not yet been settled, you can cancel it (DISABLED) and issue a new one. If it was already settled (SETTLED), the only way to revert the accounting effect is to issue a credit note (CREDIT_NOTE) that offsets the amount. See Credit notes.

Webhooks

State change	Webhook
→ PAID	receivable.paid
→ EXPIRED	receivable.expired
→ SETTLED	receivable.settled
→ DISABLED	receivable.disabled

Cancellation (DELETE)

DELETE /v1/receivables/{id}

Changes the state to DISABLED. Allowed if the receivable is in PENDING, PAID or EXPIRED and has not yet been settled.

DELETE /v1/receivables/{id} and PATCH /v1/receivables/{id}/status with { "status": "DISABLED" } are equivalent: they produce the same state change and trigger the same receivable.disabled webhook. Pick the one that best expresses intent in your integration (DELETE for "delete due to data-entry error", PATCH when your flow is already iterating through status changes).

If the receivable already has related credit notes (other receivables with parentReceivableId = id), DELETE returns 422 receivable-has-related-items. The children must be cancelled first.