// api reference

Orders

GETList orders, newest first
POSTCreate an order
GETRetrieve an order
GETAn order's transitions, oldest first
POSTClaim the deal is done (committed to claimed)
POSTConfirm a claim (claimed to completed), by the party who did not claim
POSTBack out (committed to cancelled)
POSTPropose cancelling by agreement
POSTAccept a proposal to cancel (committed to cancelled, reason mutual)
POSTDecline a proposal to cancel. The order stays committed.
GETAn order's reviews
POSTReview the other party

GET /v1/orders

List orders, newest first

secret key only

GET /v1/ordersrequest

curl https://api.marketsdk.com/v1/orders \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, order list

{
  "object": "list",
  "data": [
    {
      "object": "order",
      "id": "ord_034XtPDs7UJ0TXzTsdaHZa",
      "listing": "string",
      "buyer": "string",
      "seller": "string",
      "quantity": 0,
      "price": {
        "unit_amount": 0,
        "amount": 0,
        "currency": "USD"
      },
      "fee": {
        "amount": 4900,
        "currency": "USD"
      },
      "payments": false,
      "payment": {
        "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
        "status": "awaiting_payment",
        "checkout_url": null,
        "client_secret": null,
        "amount_refunded": 0,
        "amount_released": 0,
        "release_status": "held"
      },
      "state": "awaiting_payment",
      "state_reason": "payment_expired",
      "claimed_by": "buyer",
      "cancellation_proposal": {
        "proposed_by": "buyer",
        "expires_at": "2026-10-01T12:00:00.000Z"
      },
      "timer_expires_at": null,
      "completed_at": null,
      "review_window_closes_at": null,
      "dispute_window_closes_at": null,
      "metadata": {},
      "created_at": "2026-10-01T12:00:00.000Z",
      "updated_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
limit	integer, in query	min 1, max 100, default 20
starting_after	string, in query	The `next_cursor` of the previous page.
buyer	string, in query
seller	string, in query
listing	string, in query
state	one of: awaiting_payment, committed, claimed, disputed, completed, cancelled, expired, in query

returns 200, order list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of order
data[].objectrequired	one of: order
data[].idrequired	string
data[].listingrequired	string
data[].buyerrequired	string
data[].sellerrequired	string
data[].quantityrequired	integer
data[].pricerequired	order price
data[].price.unit_amountrequired	integer	Per unit, fixed when the order was created. Minor units.
data[].price.amountrequired	integer	unit_amount times quantity. Minor units.
data[].price.currencyrequired	string
data[].feerequired	money	The customer's platform fee, fixed when the order was created.
data[].fee.amountrequired	integer	Integer minor units.
data[].fee.currencyrequired	string
data[].paymentsrequired	boolean	Whether payments were on when the order was created.
data[].paymentrequired	order payment or null
data[].payment.idrequired	string
data[].payment.statusrequired	one of: awaiting_payment, succeeded, canceled
data[].payment.checkout_urlrequired	string or null	Stripe-hosted checkout, when checkout URLs were given.
data[].payment.client_secretrequired	string or null	For Stripe Elements on your own page, with your own Stripe publishable key.
data[].payment.amount_refundedrequired	integer	Refunded so far. Minor units.
data[].payment.amount_releasedrequired	integer	Released to the seller so far. Minor units.
data[].payment.release_statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer has paid. The seller share is held until the order completes, unless the marketplace releases at commitment.
data[].staterequired	one of: awaiting_payment, committed, claimed, disputed, completed, cancelled, expired
data[].state_reasonrequired	one of: payment_expired, backed_out, mutual, auto_confirmed, dispute, null or null
data[].claimed_byrequired	one of: buyer, seller, null or null
data[].cancellation_proposalrequired	cancellation proposal or null
data[].cancellation_proposal.proposed_byrequired	one of: buyer, seller
data[].cancellation_proposal.expires_atrequired	timestamp	The proposal lapses after this. A lapsed or declined proposal changes nothing.
data[].timer_expires_atrequired	timestamp or null	When the current state's timer passes.
data[].completed_atrequired	timestamp or null
data[].review_window_closes_atrequired	timestamp or null
data[].dispute_window_closes_atrequired	timestamp or null
data[].metadatarequired	object of strings
data[].created_atrequired	timestamp
data[].updated_atrequired	timestamp
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
429Rate limited. See Retry-After.

POST /v1/orders

Create an order

The buyer commits to buy. Quantity is reserved at once. With payments off the order is committed; with payments on it awaits payment.

secret key only

POST /v1/ordersrequest

curl -X POST https://api.marketsdk.com/v1/orders \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"listing":"lst_034XtPDs7UJ0TXzTsdaHZa","buyer":"buy_034XtPDs7UJ0TXzTsdaHZa"}'

201 example response, order

{
  "object": "order",
  "id": "ord_034XtPDs7UJ0TXzTsdaHZa",
  "listing": "string",
  "buyer": "string",
  "seller": "string",
  "quantity": 0,
  "price": {
    "unit_amount": 0,
    "amount": 0,
    "currency": "USD"
  },
  "fee": {
    "amount": 4900,
    "currency": "USD"
  },
  "payments": false,
  "payment": {
    "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
    "status": "awaiting_payment",
    "checkout_url": null,
    "client_secret": null,
    "amount_refunded": 0,
    "amount_released": 0,
    "release_status": "held"
  },
  "state": "awaiting_payment",
  "state_reason": "payment_expired",
  "claimed_by": "buyer",
  "cancellation_proposal": {
    "proposed_by": "buyer",
    "expires_at": "2026-10-01T12:00:00.000Z"
  },
  "timer_expires_at": null,
  "completed_at": null,
  "review_window_closes_at": null,
  "dispute_window_closes_at": null,
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

body, create order

Request body
field	type	about
listingrequired	string
buyerrequired	string	The buyer placing the order. The actor for this transition.
quantity	integer	min 1, default 1
checkout	checkout urls	Payments on only. With these, the order's payment includes a Stripe-hosted checkout URL; without them, a client secret for Stripe Elements on your own page.
checkout.success_urlrequired	string	Where Stripe sends the buyer after paying.
checkout.cancel_urlrequired	string	Where Stripe sends the buyer if they go back.
metadata	object of strings

returns 201, order

fields

Response fields
field	type	about
objectrequired	one of: order
idrequired	string
listingrequired	string
buyerrequired	string
sellerrequired	string
quantityrequired	integer
pricerequired	order price
price.unit_amountrequired	integer	Per unit, fixed when the order was created. Minor units.
price.amountrequired	integer	unit_amount times quantity. Minor units.
price.currencyrequired	string
feerequired	money	The customer's platform fee, fixed when the order was created.
fee.amountrequired	integer	Integer minor units.
fee.currencyrequired	string
paymentsrequired	boolean	Whether payments were on when the order was created.
paymentrequired	order payment or null
payment.idrequired	string
payment.statusrequired	one of: awaiting_payment, succeeded, canceled
payment.checkout_urlrequired	string or null	Stripe-hosted checkout, when checkout URLs were given.
payment.client_secretrequired	string or null	For Stripe Elements on your own page, with your own Stripe publishable key.
payment.amount_refundedrequired	integer	Refunded so far. Minor units.
payment.amount_releasedrequired	integer	Released to the seller so far. Minor units.
payment.release_statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer has paid. The seller share is held until the order completes, unless the marketplace releases at commitment.
staterequired	one of: awaiting_payment, committed, claimed, disputed, completed, cancelled, expired
state_reasonrequired	one of: payment_expired, backed_out, mutual, auto_confirmed, dispute, null or null
claimed_byrequired	one of: buyer, seller, null or null
cancellation_proposalrequired	cancellation proposal or null
cancellation_proposal.proposed_byrequired	one of: buyer, seller
cancellation_proposal.expires_atrequired	timestamp	The proposal lapses after this. A lapsed or declined proposal changes nothing.
timer_expires_atrequired	timestamp or null	When the current state's timer passes.
completed_atrequired	timestamp or null
review_window_closes_atrequired	timestamp or null
dispute_window_closes_atrequired	timestamp or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
403Not allowed with this key, or the marketplace is read-only.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

GET /v1/orders/{id}

Retrieve an order

secret key only

GET /v1/orders/{id}request

curl https://api.marketsdk.com/v1/orders/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, order

{
  "object": "order",
  "id": "ord_034XtPDs7UJ0TXzTsdaHZa",
  "listing": "string",
  "buyer": "string",
  "seller": "string",
  "quantity": 0,
  "price": {
    "unit_amount": 0,
    "amount": 0,
    "currency": "USD"
  },
  "fee": {
    "amount": 4900,
    "currency": "USD"
  },
  "payments": false,
  "payment": {
    "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
    "status": "awaiting_payment",
    "checkout_url": null,
    "client_secret": null,
    "amount_refunded": 0,
    "amount_released": 0,
    "release_status": "held"
  },
  "state": "awaiting_payment",
  "state_reason": "payment_expired",
  "claimed_by": "buyer",
  "cancellation_proposal": {
    "proposed_by": "buyer",
    "expires_at": "2026-10-01T12:00:00.000Z"
  },
  "timer_expires_at": null,
  "completed_at": null,
  "review_window_closes_at": null,
  "dispute_window_closes_at": null,
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, order

fields

Response fields
field	type	about
objectrequired	one of: order
idrequired	string
listingrequired	string
buyerrequired	string
sellerrequired	string
quantityrequired	integer
pricerequired	order price
price.unit_amountrequired	integer	Per unit, fixed when the order was created. Minor units.
price.amountrequired	integer	unit_amount times quantity. Minor units.
price.currencyrequired	string
feerequired	money	The customer's platform fee, fixed when the order was created.
fee.amountrequired	integer	Integer minor units.
fee.currencyrequired	string
paymentsrequired	boolean	Whether payments were on when the order was created.
paymentrequired	order payment or null
payment.idrequired	string
payment.statusrequired	one of: awaiting_payment, succeeded, canceled
payment.checkout_urlrequired	string or null	Stripe-hosted checkout, when checkout URLs were given.
payment.client_secretrequired	string or null	For Stripe Elements on your own page, with your own Stripe publishable key.
payment.amount_refundedrequired	integer	Refunded so far. Minor units.
payment.amount_releasedrequired	integer	Released to the seller so far. Minor units.
payment.release_statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer has paid. The seller share is held until the order completes, unless the marketplace releases at commitment.
staterequired	one of: awaiting_payment, committed, claimed, disputed, completed, cancelled, expired
state_reasonrequired	one of: payment_expired, backed_out, mutual, auto_confirmed, dispute, null or null
claimed_byrequired	one of: buyer, seller, null or null
cancellation_proposalrequired	cancellation proposal or null
cancellation_proposal.proposed_byrequired	one of: buyer, seller
cancellation_proposal.expires_atrequired	timestamp	The proposal lapses after this. A lapsed or declined proposal changes nothing.
timer_expires_atrequired	timestamp or null	When the current state's timer passes.
completed_atrequired	timestamp or null
review_window_closes_atrequired	timestamp or null
dispute_window_closes_atrequired	timestamp or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

GET /v1/orders/{id}/events

An order's transitions, oldest first

secret key only

GET /v1/orders/{id}/eventsrequest

curl https://api.marketsdk.com/v1/orders/{id}/events \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, order event list

{
  "object": "list",
  "data": [
    {
      "object": "order_event",
      "id": "oev_034XtPDs7UJ0TXzTsdaHZa",
      "order": "string",
      "sequence": 0,
      "from_state": null,
      "to_state": "string",
      "actor_type": "buyer",
      "actor": null,
      "reason": null,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, order event list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of order event
data[].objectrequired	one of: order_event
data[].idrequired	string
data[].orderrequired	string
data[].sequencerequired	integer
data[].from_staterequired	string or null
data[].to_staterequired	string
data[].actor_typerequired	one of: buyer, seller, system, customer
data[].actorrequired	string or null
data[].reasonrequired	string or null
data[].created_atrequired	timestamp
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

POST /v1/orders/{id}/claim

Claim the deal is done (committed to claimed)

Called from your server. actor says which end user is acting; we check they are a party to the order and may make this transition.

secret key only

POST /v1/orders/{id}/claimrequest

curl -X POST https://api.marketsdk.com/v1/orders/{id}/claim \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"actor":"buy_034XtPDs7UJ0TXzTsdaHZa"}'

200 example response, order

{
  "object": "order",
  "id": "ord_034XtPDs7UJ0TXzTsdaHZa",
  "listing": "string",
  "buyer": "string",
  "seller": "string",
  "quantity": 0,
  "price": {
    "unit_amount": 0,
    "amount": 0,
    "currency": "USD"
  },
  "fee": {
    "amount": 4900,
    "currency": "USD"
  },
  "payments": false,
  "payment": {
    "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
    "status": "awaiting_payment",
    "checkout_url": null,
    "client_secret": null,
    "amount_refunded": 0,
    "amount_released": 0,
    "release_status": "held"
  },
  "state": "awaiting_payment",
  "state_reason": "payment_expired",
  "claimed_by": "buyer",
  "cancellation_proposal": {
    "proposed_by": "buyer",
    "expires_at": "2026-10-01T12:00:00.000Z"
  },
  "timer_expires_at": null,
  "completed_at": null,
  "review_window_closes_at": null,
  "dispute_window_closes_at": null,
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, actor

Request body
field	type	about
actorrequired	string	The buyer id or seller id of the end user doing this. We check they are a party to the order and may make this transition.

returns 200, order

fields

Response fields
field	type	about
objectrequired	one of: order
idrequired	string
listingrequired	string
buyerrequired	string
sellerrequired	string
quantityrequired	integer
pricerequired	order price
price.unit_amountrequired	integer	Per unit, fixed when the order was created. Minor units.
price.amountrequired	integer	unit_amount times quantity. Minor units.
price.currencyrequired	string
feerequired	money	The customer's platform fee, fixed when the order was created.
fee.amountrequired	integer	Integer minor units.
fee.currencyrequired	string
paymentsrequired	boolean	Whether payments were on when the order was created.
paymentrequired	order payment or null
payment.idrequired	string
payment.statusrequired	one of: awaiting_payment, succeeded, canceled
payment.checkout_urlrequired	string or null	Stripe-hosted checkout, when checkout URLs were given.
payment.client_secretrequired	string or null	For Stripe Elements on your own page, with your own Stripe publishable key.
payment.amount_refundedrequired	integer	Refunded so far. Minor units.
payment.amount_releasedrequired	integer	Released to the seller so far. Minor units.
payment.release_statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer has paid. The seller share is held until the order completes, unless the marketplace releases at commitment.
staterequired	one of: awaiting_payment, committed, claimed, disputed, completed, cancelled, expired
state_reasonrequired	one of: payment_expired, backed_out, mutual, auto_confirmed, dispute, null or null
claimed_byrequired	one of: buyer, seller, null or null
cancellation_proposalrequired	cancellation proposal or null
cancellation_proposal.proposed_byrequired	one of: buyer, seller
cancellation_proposal.expires_atrequired	timestamp	The proposal lapses after this. A lapsed or declined proposal changes nothing.
timer_expires_atrequired	timestamp or null	When the current state's timer passes.
completed_atrequired	timestamp or null
review_window_closes_atrequired	timestamp or null
dispute_window_closes_atrequired	timestamp or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
403Not allowed with this key, or the marketplace is read-only.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/orders/{id}/confirm

Confirm a claim (claimed to completed), by the party who did not claim

Called from your server. actor says which end user is acting; we check they are a party to the order and may make this transition.

secret key only

POST /v1/orders/{id}/confirmrequest

curl -X POST https://api.marketsdk.com/v1/orders/{id}/confirm \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"actor":"buy_034XtPDs7UJ0TXzTsdaHZa"}'

200 example response, order

{
  "object": "order",
  "id": "ord_034XtPDs7UJ0TXzTsdaHZa",
  "listing": "string",
  "buyer": "string",
  "seller": "string",
  "quantity": 0,
  "price": {
    "unit_amount": 0,
    "amount": 0,
    "currency": "USD"
  },
  "fee": {
    "amount": 4900,
    "currency": "USD"
  },
  "payments": false,
  "payment": {
    "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
    "status": "awaiting_payment",
    "checkout_url": null,
    "client_secret": null,
    "amount_refunded": 0,
    "amount_released": 0,
    "release_status": "held"
  },
  "state": "awaiting_payment",
  "state_reason": "payment_expired",
  "claimed_by": "buyer",
  "cancellation_proposal": {
    "proposed_by": "buyer",
    "expires_at": "2026-10-01T12:00:00.000Z"
  },
  "timer_expires_at": null,
  "completed_at": null,
  "review_window_closes_at": null,
  "dispute_window_closes_at": null,
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, actor

Request body
field	type	about
actorrequired	string	The buyer id or seller id of the end user doing this. We check they are a party to the order and may make this transition.

returns 200, order

fields

Response fields
field	type	about
objectrequired	one of: order
idrequired	string
listingrequired	string
buyerrequired	string
sellerrequired	string
quantityrequired	integer
pricerequired	order price
price.unit_amountrequired	integer	Per unit, fixed when the order was created. Minor units.
price.amountrequired	integer	unit_amount times quantity. Minor units.
price.currencyrequired	string
feerequired	money	The customer's platform fee, fixed when the order was created.
fee.amountrequired	integer	Integer minor units.
fee.currencyrequired	string
paymentsrequired	boolean	Whether payments were on when the order was created.
paymentrequired	order payment or null
payment.idrequired	string
payment.statusrequired	one of: awaiting_payment, succeeded, canceled
payment.checkout_urlrequired	string or null	Stripe-hosted checkout, when checkout URLs were given.
payment.client_secretrequired	string or null	For Stripe Elements on your own page, with your own Stripe publishable key.
payment.amount_refundedrequired	integer	Refunded so far. Minor units.
payment.amount_releasedrequired	integer	Released to the seller so far. Minor units.
payment.release_statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer has paid. The seller share is held until the order completes, unless the marketplace releases at commitment.
staterequired	one of: awaiting_payment, committed, claimed, disputed, completed, cancelled, expired
state_reasonrequired	one of: payment_expired, backed_out, mutual, auto_confirmed, dispute, null or null
claimed_byrequired	one of: buyer, seller, null or null
cancellation_proposalrequired	cancellation proposal or null
cancellation_proposal.proposed_byrequired	one of: buyer, seller
cancellation_proposal.expires_atrequired	timestamp	The proposal lapses after this. A lapsed or declined proposal changes nothing.
timer_expires_atrequired	timestamp or null	When the current state's timer passes.
completed_atrequired	timestamp or null
review_window_closes_atrequired	timestamp or null
dispute_window_closes_atrequired	timestamp or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
403Not allowed with this key, or the marketplace is read-only.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/orders/{id}/back_out

Back out (committed to cancelled)

Called from your server. actor says which end user is acting; we check they are a party to the order and may make this transition. Writes a backed_out reputation event against the actor.

secret key only

POST /v1/orders/{id}/back_outrequest

curl -X POST https://api.marketsdk.com/v1/orders/{id}/back_out \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"actor":"buy_034XtPDs7UJ0TXzTsdaHZa"}'

200 example response, order

{
  "object": "order",
  "id": "ord_034XtPDs7UJ0TXzTsdaHZa",
  "listing": "string",
  "buyer": "string",
  "seller": "string",
  "quantity": 0,
  "price": {
    "unit_amount": 0,
    "amount": 0,
    "currency": "USD"
  },
  "fee": {
    "amount": 4900,
    "currency": "USD"
  },
  "payments": false,
  "payment": {
    "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
    "status": "awaiting_payment",
    "checkout_url": null,
    "client_secret": null,
    "amount_refunded": 0,
    "amount_released": 0,
    "release_status": "held"
  },
  "state": "awaiting_payment",
  "state_reason": "payment_expired",
  "claimed_by": "buyer",
  "cancellation_proposal": {
    "proposed_by": "buyer",
    "expires_at": "2026-10-01T12:00:00.000Z"
  },
  "timer_expires_at": null,
  "completed_at": null,
  "review_window_closes_at": null,
  "dispute_window_closes_at": null,
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, actor

Request body
field	type	about
actorrequired	string	The buyer id or seller id of the end user doing this. We check they are a party to the order and may make this transition.

returns 200, order

fields

Response fields
field	type	about
objectrequired	one of: order
idrequired	string
listingrequired	string
buyerrequired	string
sellerrequired	string
quantityrequired	integer
pricerequired	order price
price.unit_amountrequired	integer	Per unit, fixed when the order was created. Minor units.
price.amountrequired	integer	unit_amount times quantity. Minor units.
price.currencyrequired	string
feerequired	money	The customer's platform fee, fixed when the order was created.
fee.amountrequired	integer	Integer minor units.
fee.currencyrequired	string
paymentsrequired	boolean	Whether payments were on when the order was created.
paymentrequired	order payment or null
payment.idrequired	string
payment.statusrequired	one of: awaiting_payment, succeeded, canceled
payment.checkout_urlrequired	string or null	Stripe-hosted checkout, when checkout URLs were given.
payment.client_secretrequired	string or null	For Stripe Elements on your own page, with your own Stripe publishable key.
payment.amount_refundedrequired	integer	Refunded so far. Minor units.
payment.amount_releasedrequired	integer	Released to the seller so far. Minor units.
payment.release_statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer has paid. The seller share is held until the order completes, unless the marketplace releases at commitment.
staterequired	one of: awaiting_payment, committed, claimed, disputed, completed, cancelled, expired
state_reasonrequired	one of: payment_expired, backed_out, mutual, auto_confirmed, dispute, null or null
claimed_byrequired	one of: buyer, seller, null or null
cancellation_proposalrequired	cancellation proposal or null
cancellation_proposal.proposed_byrequired	one of: buyer, seller
cancellation_proposal.expires_atrequired	timestamp	The proposal lapses after this. A lapsed or declined proposal changes nothing.
timer_expires_atrequired	timestamp or null	When the current state's timer passes.
completed_atrequired	timestamp or null
review_window_closes_atrequired	timestamp or null
dispute_window_closes_atrequired	timestamp or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
403Not allowed with this key, or the marketplace is read-only.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/orders/{id}/propose_cancel

Propose cancelling by agreement

Called from your server. actor says which end user is acting; we check they are a party to the order and may make this transition. The other party can accept within the agreement window. A declined or lapsed proposal changes nothing.

secret key only

POST /v1/orders/{id}/propose_cancelrequest

curl -X POST https://api.marketsdk.com/v1/orders/{id}/propose_cancel \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"actor":"buy_034XtPDs7UJ0TXzTsdaHZa"}'

200 example response, order

{
  "object": "order",
  "id": "ord_034XtPDs7UJ0TXzTsdaHZa",
  "listing": "string",
  "buyer": "string",
  "seller": "string",
  "quantity": 0,
  "price": {
    "unit_amount": 0,
    "amount": 0,
    "currency": "USD"
  },
  "fee": {
    "amount": 4900,
    "currency": "USD"
  },
  "payments": false,
  "payment": {
    "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
    "status": "awaiting_payment",
    "checkout_url": null,
    "client_secret": null,
    "amount_refunded": 0,
    "amount_released": 0,
    "release_status": "held"
  },
  "state": "awaiting_payment",
  "state_reason": "payment_expired",
  "claimed_by": "buyer",
  "cancellation_proposal": {
    "proposed_by": "buyer",
    "expires_at": "2026-10-01T12:00:00.000Z"
  },
  "timer_expires_at": null,
  "completed_at": null,
  "review_window_closes_at": null,
  "dispute_window_closes_at": null,
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, actor

Request body
field	type	about
actorrequired	string	The buyer id or seller id of the end user doing this. We check they are a party to the order and may make this transition.

returns 200, order

fields

Response fields
field	type	about
objectrequired	one of: order
idrequired	string
listingrequired	string
buyerrequired	string
sellerrequired	string
quantityrequired	integer
pricerequired	order price
price.unit_amountrequired	integer	Per unit, fixed when the order was created. Minor units.
price.amountrequired	integer	unit_amount times quantity. Minor units.
price.currencyrequired	string
feerequired	money	The customer's platform fee, fixed when the order was created.
fee.amountrequired	integer	Integer minor units.
fee.currencyrequired	string
paymentsrequired	boolean	Whether payments were on when the order was created.
paymentrequired	order payment or null
payment.idrequired	string
payment.statusrequired	one of: awaiting_payment, succeeded, canceled
payment.checkout_urlrequired	string or null	Stripe-hosted checkout, when checkout URLs were given.
payment.client_secretrequired	string or null	For Stripe Elements on your own page, with your own Stripe publishable key.
payment.amount_refundedrequired	integer	Refunded so far. Minor units.
payment.amount_releasedrequired	integer	Released to the seller so far. Minor units.
payment.release_statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer has paid. The seller share is held until the order completes, unless the marketplace releases at commitment.
staterequired	one of: awaiting_payment, committed, claimed, disputed, completed, cancelled, expired
state_reasonrequired	one of: payment_expired, backed_out, mutual, auto_confirmed, dispute, null or null
claimed_byrequired	one of: buyer, seller, null or null
cancellation_proposalrequired	cancellation proposal or null
cancellation_proposal.proposed_byrequired	one of: buyer, seller
cancellation_proposal.expires_atrequired	timestamp	The proposal lapses after this. A lapsed or declined proposal changes nothing.
timer_expires_atrequired	timestamp or null	When the current state's timer passes.
completed_atrequired	timestamp or null
review_window_closes_atrequired	timestamp or null
dispute_window_closes_atrequired	timestamp or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
403Not allowed with this key, or the marketplace is read-only.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/orders/{id}/accept_cancel

Accept a proposal to cancel (committed to cancelled, reason mutual)

Called from your server. actor says which end user is acting; we check they are a party to the order and may make this transition.

secret key only

POST /v1/orders/{id}/accept_cancelrequest

curl -X POST https://api.marketsdk.com/v1/orders/{id}/accept_cancel \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"actor":"buy_034XtPDs7UJ0TXzTsdaHZa"}'

200 example response, order

{
  "object": "order",
  "id": "ord_034XtPDs7UJ0TXzTsdaHZa",
  "listing": "string",
  "buyer": "string",
  "seller": "string",
  "quantity": 0,
  "price": {
    "unit_amount": 0,
    "amount": 0,
    "currency": "USD"
  },
  "fee": {
    "amount": 4900,
    "currency": "USD"
  },
  "payments": false,
  "payment": {
    "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
    "status": "awaiting_payment",
    "checkout_url": null,
    "client_secret": null,
    "amount_refunded": 0,
    "amount_released": 0,
    "release_status": "held"
  },
  "state": "awaiting_payment",
  "state_reason": "payment_expired",
  "claimed_by": "buyer",
  "cancellation_proposal": {
    "proposed_by": "buyer",
    "expires_at": "2026-10-01T12:00:00.000Z"
  },
  "timer_expires_at": null,
  "completed_at": null,
  "review_window_closes_at": null,
  "dispute_window_closes_at": null,
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, actor

Request body
field	type	about
actorrequired	string	The buyer id or seller id of the end user doing this. We check they are a party to the order and may make this transition.

returns 200, order

fields

Response fields
field	type	about
objectrequired	one of: order
idrequired	string
listingrequired	string
buyerrequired	string
sellerrequired	string
quantityrequired	integer
pricerequired	order price
price.unit_amountrequired	integer	Per unit, fixed when the order was created. Minor units.
price.amountrequired	integer	unit_amount times quantity. Minor units.
price.currencyrequired	string
feerequired	money	The customer's platform fee, fixed when the order was created.
fee.amountrequired	integer	Integer minor units.
fee.currencyrequired	string
paymentsrequired	boolean	Whether payments were on when the order was created.
paymentrequired	order payment or null
payment.idrequired	string
payment.statusrequired	one of: awaiting_payment, succeeded, canceled
payment.checkout_urlrequired	string or null	Stripe-hosted checkout, when checkout URLs were given.
payment.client_secretrequired	string or null	For Stripe Elements on your own page, with your own Stripe publishable key.
payment.amount_refundedrequired	integer	Refunded so far. Minor units.
payment.amount_releasedrequired	integer	Released to the seller so far. Minor units.
payment.release_statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer has paid. The seller share is held until the order completes, unless the marketplace releases at commitment.
staterequired	one of: awaiting_payment, committed, claimed, disputed, completed, cancelled, expired
state_reasonrequired	one of: payment_expired, backed_out, mutual, auto_confirmed, dispute, null or null
claimed_byrequired	one of: buyer, seller, null or null
cancellation_proposalrequired	cancellation proposal or null
cancellation_proposal.proposed_byrequired	one of: buyer, seller
cancellation_proposal.expires_atrequired	timestamp	The proposal lapses after this. A lapsed or declined proposal changes nothing.
timer_expires_atrequired	timestamp or null	When the current state's timer passes.
completed_atrequired	timestamp or null
review_window_closes_atrequired	timestamp or null
dispute_window_closes_atrequired	timestamp or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
403Not allowed with this key, or the marketplace is read-only.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/orders/{id}/decline_cancel

Decline a proposal to cancel. The order stays committed.

Called from your server. actor says which end user is acting; we check they are a party to the order and may make this transition.

secret key only

POST /v1/orders/{id}/decline_cancelrequest

curl -X POST https://api.marketsdk.com/v1/orders/{id}/decline_cancel \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"actor":"buy_034XtPDs7UJ0TXzTsdaHZa"}'

200 example response, order

{
  "object": "order",
  "id": "ord_034XtPDs7UJ0TXzTsdaHZa",
  "listing": "string",
  "buyer": "string",
  "seller": "string",
  "quantity": 0,
  "price": {
    "unit_amount": 0,
    "amount": 0,
    "currency": "USD"
  },
  "fee": {
    "amount": 4900,
    "currency": "USD"
  },
  "payments": false,
  "payment": {
    "id": "pay_034XtPDs7UJ0TXzTsdaHZa",
    "status": "awaiting_payment",
    "checkout_url": null,
    "client_secret": null,
    "amount_refunded": 0,
    "amount_released": 0,
    "release_status": "held"
  },
  "state": "awaiting_payment",
  "state_reason": "payment_expired",
  "claimed_by": "buyer",
  "cancellation_proposal": {
    "proposed_by": "buyer",
    "expires_at": "2026-10-01T12:00:00.000Z"
  },
  "timer_expires_at": null,
  "completed_at": null,
  "review_window_closes_at": null,
  "dispute_window_closes_at": null,
  "metadata": {},
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, actor

Request body
field	type	about
actorrequired	string	The buyer id or seller id of the end user doing this. We check they are a party to the order and may make this transition.

returns 200, order

fields

Response fields
field	type	about
objectrequired	one of: order
idrequired	string
listingrequired	string
buyerrequired	string
sellerrequired	string
quantityrequired	integer
pricerequired	order price
price.unit_amountrequired	integer	Per unit, fixed when the order was created. Minor units.
price.amountrequired	integer	unit_amount times quantity. Minor units.
price.currencyrequired	string
feerequired	money	The customer's platform fee, fixed when the order was created.
fee.amountrequired	integer	Integer minor units.
fee.currencyrequired	string
paymentsrequired	boolean	Whether payments were on when the order was created.
paymentrequired	order payment or null
payment.idrequired	string
payment.statusrequired	one of: awaiting_payment, succeeded, canceled
payment.checkout_urlrequired	string or null	Stripe-hosted checkout, when checkout URLs were given.
payment.client_secretrequired	string or null	For Stripe Elements on your own page, with your own Stripe publishable key.
payment.amount_refundedrequired	integer	Refunded so far. Minor units.
payment.amount_releasedrequired	integer	Released to the seller so far. Minor units.
payment.release_statusrequired	one of: held, releasing, released, failed, nothing_to_release, null or null	Null until the buyer has paid. The seller share is held until the order completes, unless the marketplace releases at commitment.
staterequired	one of: awaiting_payment, committed, claimed, disputed, completed, cancelled, expired
state_reasonrequired	one of: payment_expired, backed_out, mutual, auto_confirmed, dispute, null or null
claimed_byrequired	one of: buyer, seller, null or null
cancellation_proposalrequired	cancellation proposal or null
cancellation_proposal.proposed_byrequired	one of: buyer, seller
cancellation_proposal.expires_atrequired	timestamp	The proposal lapses after this. A lapsed or declined proposal changes nothing.
timer_expires_atrequired	timestamp or null	When the current state's timer passes.
completed_atrequired	timestamp or null
review_window_closes_atrequired	timestamp or null
dispute_window_closes_atrequired	timestamp or null
metadatarequired	object of strings
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
403Not allowed with this key, or the marketplace is read-only.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

GET /v1/orders/{id}/reviews

An order's reviews

secret key only

GET /v1/orders/{id}/reviewsrequest

curl https://api.marketsdk.com/v1/orders/{id}/reviews \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, review list

{
  "object": "list",
  "data": [
    {
      "object": "review",
      "id": "rev_034XtPDs7UJ0TXzTsdaHZa",
      "order": "string",
      "author_role": "buyer",
      "author": "string",
      "subject": "string",
      "visible": false,
      "rating": null,
      "body": null,
      "removed": false,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, review list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of review
data[].objectrequired	one of: review
data[].idrequired	string
data[].orderrequired	string
data[].author_rolerequired	one of: buyer, seller
data[].authorrequired	string
data[].subjectrequired	string
data[].visiblerequired	boolean	False until both parties have reviewed or the review window has closed. Rating and body are withheld until then.
data[].ratingrequired	integer or null	min 1, max 5
data[].bodyrequired	string or null
data[].removedrequired	boolean	Removed by moderation. A removed review stops counting toward reputation.
data[].created_atrequired	timestamp
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

POST /v1/orders/{id}/reviews

Review the other party

Called from your server. actor says which end user is acting; we check they are a party to the order and may make this transition. Only on a completed order, inside the review window, once per party. Hidden until both have reviewed or the window closes.

secret key only

POST /v1/orders/{id}/reviewsrequest

curl -X POST https://api.marketsdk.com/v1/orders/{id}/reviews \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"actor":"buy_034XtPDs7UJ0TXzTsdaHZa","rating":1}'

201 example response, review

{
  "object": "review",
  "id": "rev_034XtPDs7UJ0TXzTsdaHZa",
  "order": "string",
  "author_role": "buyer",
  "author": "string",
  "subject": "string",
  "visible": false,
  "rating": null,
  "body": null,
  "removed": false,
  "created_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, create review

Request body
field	type	about
actorrequired	string	The buyer id or seller id of the end user doing this. We check they are a party to the order and may make this transition.
ratingrequired	integer	min 1, max 5
body	string	up to 5000 characters

returns 201, review

fields

Response fields
field	type	about
objectrequired	one of: review
idrequired	string
orderrequired	string
author_rolerequired	one of: buyer, seller
authorrequired	string
subjectrequired	string
visiblerequired	boolean	False until both parties have reviewed or the review window has closed. Rating and body are withheld until then.
ratingrequired	integer or null	min 1, max 5
bodyrequired	string or null
removedrequired	boolean	Removed by moderation. A removed review stops counting toward reputation.
created_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
403Not allowed with this key, or the marketplace is read-only.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.