Skip to main content
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.
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.

​
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:
The escrow’s totalQuantity > 1.
The escrow was created through the API (channel: "API").
The seller is eligible — a business account or a merchant customer (merchant_user).
The link is not sold out yet (it has been duplicated fewer than totalQuantity times).
If any condition fails, the payment funds the escrow normally with no clone — exactly like a single-quantity escrow.

​
What happens on each purchase

Step by step, when the buyer calls POST /v1/payment/escrow against a multi-quantity link:
1

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

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

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

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

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.

​
A worked example

You create one escrow: amount: 50000, totalQuantity: 3.
EventOriginal linkClone createdClone state
CreatedtotalQuantity: 3, AWAITING_PAYMENT——
Buyer A pays & verifiestotalQuantity: 2, AWAITING_PAYMENTClone #1OPENED (A’s)
Buyer B pays & verifiestotalQuantity: 1, AWAITING_PAYMENTClone #2OPENED (B’s)
Buyer C pays & verifiestotalQuantity: 0, AWAITING_PAYMENTClone #3OPENED (C’s)
Buyer D tries to paysold out — no clone—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

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.
Milestone escrows are funded in full by one buyer and released in stages — the multi-quantity/stock model does not apply to them.
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.