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

# Escrow lifecycle

> How an escrow moves from creation to settlement, and what state and status mean.

Every escrow tracks two related fields:

* **`state`**: where the escrow is in its lifecycle: `AWAITING_PAYMENT` → `OPENED` → `CLOSED`.
* **`status`**: the business outcome: `PENDING`, `ONGOING`, `COMPLETED`, `REFUNDED`, `CLAIMED`, `DISPUTED`, or `INVESTIGATING`.

## The happy path

<Steps>
  <Step title="AWAITING_PAYMENT / PENDING">
    The escrow was created via [Create escrow](/api-reference/escrow/create-escrow).
    It can still be [edited](/api-reference/escrow/edit-escrow) or
    [deleted](/api-reference/escrow/delete-escrow) by the seller while in this state.
  </Step>

  <Step title="OPENED / ONGOING">
    The buyer funded the escrow via [Pay escrow](/api-reference/payments/pay-escrow-buy).
    Funds are held by Payluk. The delivery window (`maxDelivery` + `deliveryTimeline`) starts counting.
  </Step>

  <Step title="CLOSED / COMPLETED">
    The buyer [confirms delivery](/api-reference/disputes/buyer-confirm-payment-standard),
    releasing funds to the seller. Commission is charged on completion.
  </Step>
</Steps>

## Alternate outcomes

<AccordionGroup>
  <Accordion title="Seller claims funds (CLAIMED)">
    If the delivery window elapses and the buyer hasn't confirmed, the seller
    can call [Claim funds](/api-reference/escrow/claim-funds). This is only
    allowed when the escrow is `OPENED` and the window has passed.
  </Accordion>

  <Accordion title="Dispute opened (DISPUTED / INVESTIGATING)">
    Only the buyer can [open a dispute](/api-reference/disputes/submit-dispute)
    while the escrow is `OPENED`; the seller can only respond once one is raised.
    The merchant then [resolves it](/api-reference/disputes/resolve-dispute).
    [Milestone escrows](/concepts/milestone-escrows) can't be disputed.
  </Accordion>

  <Accordion title="Refunded (REFUNDED)">
    When a merchant resolves a dispute in the buyer's favour, funds are returned
    to the buyer and the escrow closes as `REFUNDED`.
  </Accordion>
</AccordionGroup>

## State reference

| State              | Meaning                                              |
| ------------------ | ---------------------------------------------------- |
| `AWAITING_PAYMENT` | Created but not yet funded. Editable/deletable.      |
| `OPENED`           | Funded and held. Delivery in progress.               |
| `CLOSED`           | Terminal. Settled, refunded, or otherwise finalised. |

See the full [status reference](/essentials/status-reference) for how `status`
values combine with each state, and [How it works (end-to-end)](/concepts/how-it-works)
for the exact endpoints to call at each stage. If you sell more than one unit off
a single link, read [Multi-quantity escrows](/concepts/multi-quantity-escrows).