// guide

Orders

One buyer, one seller, one listing, a quantity, and a price fixed when the order is made. The order moves through a fixed set of states, and only the right party can move it.

Who acts

Every call comes from your server with a secret key. You say which of your users is acting by passing actor, a buyer id or a seller id. We trust that, and check only that the actor is a party to the order and may make that change now.

POST /v1/orders/{id}/claimrequest body

{ "actor": "sel_034XtPDs7UJ0TXzTsdaHZa" }

A buyer cannot order from a seller with the same external_id: that is one person on both sides.

States

Order states
state	means	final
`awaiting_payment`	Created, payment not confirmed yet. Only when payments are on.	no
`committed`	The buyer has committed to buy. The quantity is reserved.	no
`claimed`	One party says the deal is done and waits for the other.	no
`disputed`	A party contested the claim. A dispute is open.	no
`completed`	The deal is done.	yes
`cancelled`	The deal did not happen.	yes
`expired`	Nobody acted in time.	yes

An order in a final state never changes state again. A dispute opened after completion is recorded against the order without changing its state.

Every change an order can make

Order transitions
#	from	to	how	who
1	`none`	`awaiting_payment`	POST /v1/orders, payments on	buyer
2	`none`	`committed`	POST /v1/orders, payments off	buyer
3	`awaiting_payment`	`committed`	Stripe confirms the payment	MarketSDK
4	`awaiting_payment`	`cancelled`	the payment window passes; reason payment_expired	MarketSDK
5	`committed`	`claimed`	POST /claim	buyer or seller
6	`committed`	`cancelled`	POST /back_out; reason backed_out	buyer or seller
7	`committed`	`cancelled`	POST /propose_cancel, then POST /accept_cancel by the other party; reason mutual	both
8	`committed`	`expired`	the commitment window passes with no claim	MarketSDK
9	`claimed`	`completed`	POST /confirm	the party who did not claim
10	`claimed`	`completed`	the confirmation window passes; reason auto_confirmed	MarketSDK
11	`claimed`	`disputed`	POST /disputes	the party who did not claim
12	`disputed`	`completed`	your team decides against the party who disputed	your team
13	`disputed`	`cancelled`	your team decides against the claimant; reason dispute	your team

Anything not in this table is refused: 409 invalid_state, with a message naming the current state, or 403 actor_not_permitted when the change exists but this party may not make it.
A proposal to cancel by agreement that is declined, or not answered within the agreement window, changes nothing. The order stays committed.
Every change writes one order event: from, to, actor, reason, and time. Read them from GET /v1/orders/{id}/events. Each also sends a webhook.

Timers

Set them under marketplace in the dashboard. A value outside the limits is refused. When a timer passes, the order changes within five minutes, whether or not anyone reads it.

Order timers
timer	default	limits	starts when
payment window	30 minutes	5 minutes to 24 hours	the order awaits payment
commitment window	14 days	1 to 90 days	the order is committed
agreement window	48 hours	1 hour to 7 days	a party proposes cancelling
confirmation window	7 days	1 to 30 days	the order is claimed
review window	30 days	7 to 90 days	the order completes
dispute window	14 days	0 to 60 days	the order completes

The order shows when its current timer runs out as timer_expires_at.

Quantity

A listing has a quantity, 1 unless you say otherwise. Making an order reserves its quantity at once.
Two buyers racing for the last unit never both succeed. The loser gets 409 quantity_unavailable.
A cancelled or expired order gives its quantity back. A completed order uses it up; when none is left, the listing becomes sold.
A published listing with nothing available is left out of search.

Money, when payments are on

What each change does to the money
the order	the money
becomes committed	the buyer's payment is taken and held on your Stripe account
completes	released to the seller, less your platform fee
is cancelled or expires	refunded to the buyer in full
has a dispute decided	as the decision says: released, refunded, or split

The details are in payments and payouts.

next: reputation