> ## 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.

# Multi-quantity escrows (totalQuantity)

> How one escrow link with totalQuantity > 1 mints a separate escrow per buyer, so the same link can be sold many times.

When you create an escrow with **`totalQuantity` greater than 1**, you're not
creating one escrow that many people share; you're creating a **reusable link
with stock**. Each buyer who pays gets their **own private copy** of the escrow,
while the original link stays open for the next buyer. This page explains exactly
what happens and why.

<Info>
  Think of the original escrow as a **product listing with N units in stock**, not
  as a single transaction. The listing never gets "used up" by one buyer; instead
  it **spawns a fresh escrow per sale** and counts its stock down.
</Info>

## Why duplication exists

A standard escrow moves through one lifecycle: `AWAITING_PAYMENT → OPENED →
CLOSED`. Once a buyer funds it, it's `OPENED` and locked to that buyer. If you
want to sell the **same item to 10 different buyers from one link**, a single
escrow can't represent 10 independent lifecycles.

So Payluk **clones** the escrow at payment time: the buyer's money attaches to a
brand-new copy (its own `id`, its own `paymentToken`, its own lifecycle), and the
original link is left untouched and `AWAITING_PAYMENT` so the next buyer can pay
too. The original's `totalQuantity` is the **remaining stock counter**.

## When duplication happens

Duplication is **not** universal. A clone is minted only when **all** of these
are true at payment time:

<Check>The escrow's **`totalQuantity` > 1**.</Check>
<Check>The escrow was created through the **API** (`channel: "API"`).</Check>
<Check>The seller is eligible: a **business account** or a **merchant customer** (`merchant_user`).</Check>
<Check>The link is **not sold out** yet (it has been duplicated fewer than `totalQuantity` times).</Check>

If any condition fails, the payment funds the escrow normally with **no** clone,
exactly like a single-quantity escrow.

## What happens on each purchase

```mermaid theme={null}
sequenceDiagram
  participant Buyer
  participant API as Payluk API
  participant Orig as Original link (stock = N)
  participant Clone as Fresh clone

  Buyer->>API: POST /v1/payment/escrow (escrowId = original)
  API->>Orig: eligible & stock left?
  API->>Clone: mint copy (new id + paymentToken, AWAITING_PAYMENT)
  API-->>API: attach buyer's payment to the CLONE
  Note over API: payment verified
  API->>Clone: OPENED (this buyer's lifecycle)
  API->>Orig: totalQuantity = N − 1, sold-count + 1
  Note over Orig: still AWAITING_PAYMENT, ready for next buyer
```

Step by step, when the buyer calls
[`POST /v1/payment/escrow`](/api-reference/payments/pay-escrow-buy) against a
multi-quantity link:

<Steps>
  <Step title="Eligibility & stock check">
    Payluk confirms the four conditions above and checks how many times this link
    has already been duplicated. If it has been duplicated `totalQuantity` times,
    it's **sold out** and no clone is made.
  </Step>

  <Step title="A clone is minted">
    A new escrow is created copying the original's `amount`, `purpose`,
    `description`, `whoPays`, `maxDelivery`, `deliveryTimeline`, image and channel,
    with a **fresh `id` and `paymentToken`**, a freshly calculated `fee`, and
    `state: AWAITING_PAYMENT`.
  </Step>

  <Step title="The payment re-points to the clone">
    The buyer's payment is attached to the **clone's** `escrowId`, not the
    original. So this buyer's funds, delivery window, confirmation and any dispute
    all run on their own copy, completely isolated from other buyers.
  </Step>

  <Step title="On successful verification, stock decrements">
    Once the payment verifies, the **original** link's `totalQuantity` is reduced
    by 1 and its internal sold-counter is incremented. The original stays
    `AWAITING_PAYMENT`, ready for the next buyer.
  </Step>

  <Step title="If the payment fails">
    The half-created clone is cleaned up (deleted while still `AWAITING_PAYMENT`),
    so failed attempts don't leave orphan escrows or wrongly consume stock.
  </Step>
</Steps>

## A worked example

You create one escrow: `amount: 50000`, `totalQuantity: 3`.

| Event                   | Original link                          | Clone created | Clone state                 |
| ----------------------- | -------------------------------------- | ------------- | --------------------------- |
| Created                 | `totalQuantity: 3`, `AWAITING_PAYMENT` | none          | none                        |
| Buyer A pays & verifies | `totalQuantity: 2`, `AWAITING_PAYMENT` | Clone #1      | `OPENED` (A's)              |
| Buyer B pays & verifies | `totalQuantity: 1`, `AWAITING_PAYMENT` | Clone #2      | `OPENED` (B's)              |
| Buyer C pays & verifies | `totalQuantity: 0`, `AWAITING_PAYMENT` | Clone #3      | `OPENED` (C's)              |
| Buyer D tries to pay    | **sold out**: no clone                 | none          | payment funds nothing extra |

Each clone then runs its **own** standard flow: Buyer A can confirm or dispute
without affecting Buyers B and C.

## What this means for your integration

<AccordionGroup>
  <Accordion title="Track the clone's id, not the link's">
    After [`POST /v1/payment/escrow`](/api-reference/payments/pay-escrow-buy), the
    funded escrow is the **clone**. Read the returned escrow `id` (or watch your
    [escrow transactions](/api-reference/escrow/list-escrow-transactions)) and use
    **that** id for confirm-payment, claims and disputes, not the original
    `paymentToken`.
  </Accordion>

  <Accordion title="The original paymentToken is your shareable link">
    Keep sharing the **original** `paymentToken`. It stays valid and
    `AWAITING_PAYMENT` until stock reaches 0. You don't generate a new link per
    buyer; Payluk does the cloning for you.
  </Accordion>

  <Accordion title="Single-quantity = no surprises">
    With `totalQuantity: 1` (or unset), there is no duplication. The buyer funds
    the escrow you created and its `id` is the one you keep using.
  </Accordion>

  <Accordion title="Milestone escrows">
    Milestone escrows are funded in full by one buyer and released in stages; the
    multi-quantity/stock model does not apply to them.
  </Accordion>
</AccordionGroup>

<Note>
  In short: **`totalQuantity` is stock on a reusable link.** Each sale clones the
  escrow so every buyer gets an isolated lifecycle, and the original counts down
  until it's sold out.
</Note>