// api reference

Trust

POSTStart a seller's identity verification
GETList identity verifications, newest first
GETRetrieve an identity verification
POSTCancel a verification the seller has not submitted
GETList disputes, newest first
GETRetrieve a dispute
GETA dispute's evidence, oldest first
POSTAdd evidence from one side
POSTEnd the evidence stage early
POSTDecide a dispute
POSTDispute an order

POST /v1/sellers/{id}/verifications

Start a seller's identity verification

Creates a Stripe Identity session on your Stripe account and returns its page, once. Only the outcome and the session id are kept; no document image or document data. When seller verification is on, a seller can publish only once verified.

secret key only

POST /v1/sellers/{id}/verificationsrequest

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

201 example response, verification

{
  "object": "verification",
  "id": "ver_034XtPDs7UJ0TXzTsdaHZa",
  "seller": "string",
  "status": "requires_input",
  "last_error_code": null,
  "url": null,
  "stripe_session": null,
  "verified_at": null,
  "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, create verification

Request body
field	type	about
return_url	string	Where Stripe sends the seller after the verification page.

returns 201, verification

fields

Response fields
field	type	about
objectrequired	one of: verification
idrequired	string
sellerrequired	string
statusrequired	one of: requires_input, processing, verified, canceled	Stripe Identity's status for this attempt. `requires_input` with a `last_error_code` means the seller must try again.
last_error_coderequired	string or null	Stripe's reason the last attempt failed, such as `document_expired`.
urlrequired	string or null	The Stripe-hosted verification page. Returned only when the verification is created. Send the seller there.
stripe_sessionrequired	string or null	The Stripe Identity verification session.
verified_atrequired	timestamp or null
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/verifications

List identity verifications, newest first

secret key only

GET /v1/verificationsrequest

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

200 example response, verification list

{
  "object": "list",
  "data": [
    {
      "object": "verification",
      "id": "ver_034XtPDs7UJ0TXzTsdaHZa",
      "seller": "string",
      "status": "requires_input",
      "last_error_code": null,
      "url": null,
      "stripe_session": null,
      "verified_at": null,
      "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.
seller	string, in query

returns 200, verification list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of verification
data[].objectrequired	one of: verification
data[].idrequired	string
data[].sellerrequired	string
data[].statusrequired	one of: requires_input, processing, verified, canceled	Stripe Identity's status for this attempt. `requires_input` with a `last_error_code` means the seller must try again.
data[].last_error_coderequired	string or null	Stripe's reason the last attempt failed, such as `document_expired`.
data[].urlrequired	string or null	The Stripe-hosted verification page. Returned only when the verification is created. Send the seller there.
data[].stripe_sessionrequired	string or null	The Stripe Identity verification session.
data[].verified_atrequired	timestamp or null
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.

GET /v1/verifications/{id}

Retrieve an identity verification

secret key only

GET /v1/verifications/{id}request

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

200 example response, verification

{
  "object": "verification",
  "id": "ver_034XtPDs7UJ0TXzTsdaHZa",
  "seller": "string",
  "status": "requires_input",
  "last_error_code": null,
  "url": null,
  "stripe_session": null,
  "verified_at": null,
  "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, verification

fields

Response fields
field	type	about
objectrequired	one of: verification
idrequired	string
sellerrequired	string
statusrequired	one of: requires_input, processing, verified, canceled	Stripe Identity's status for this attempt. `requires_input` with a `last_error_code` means the seller must try again.
last_error_coderequired	string or null	Stripe's reason the last attempt failed, such as `document_expired`.
urlrequired	string or null	The Stripe-hosted verification page. Returned only when the verification is created. Send the seller there.
stripe_sessionrequired	string or null	The Stripe Identity verification session.
verified_atrequired	timestamp or null
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.

POST /v1/verifications/{id}/cancel

Cancel a verification the seller has not submitted

secret key only

POST /v1/verifications/{id}/cancelrequest

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

200 example response, verification

{
  "object": "verification",
  "id": "ver_034XtPDs7UJ0TXzTsdaHZa",
  "seller": "string",
  "status": "requires_input",
  "last_error_code": null,
  "url": null,
  "stripe_session": null,
  "verified_at": null,
  "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, verification

fields

Response fields
field	type	about
objectrequired	one of: verification
idrequired	string
sellerrequired	string
statusrequired	one of: requires_input, processing, verified, canceled	Stripe Identity's status for this attempt. `requires_input` with a `last_error_code` means the seller must try again.
last_error_coderequired	string or null	Stripe's reason the last attempt failed, such as `document_expired`.
urlrequired	string or null	The Stripe-hosted verification page. Returned only when the verification is created. Send the seller there.
stripe_sessionrequired	string or null	The Stripe Identity verification session.
verified_atrequired	timestamp or null
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.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

GET /v1/disputes

List disputes, newest first

Filter by stage for a queue.

secret key only

GET /v1/disputesrequest

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

200 example response, dispute list

{
  "object": "list",
  "data": [
    {
      "object": "dispute",
      "id": "dsp_034XtPDs7UJ0TXzTsdaHZa",
      "order": "string",
      "kind": "claimed_order",
      "opened_by": "buyer",
      "opener": "string",
      "reason": null,
      "stage": "evidence",
      "evidence_due_at": "2026-10-01T12:00:00.000Z",
      "decision_due_at": null,
      "overdue": false,
      "evidence_count": 0,
      "decision": {
        "against": "buyer",
        "outcome": "claim_upheld",
        "refund_amount": null,
        "note": "string",
        "decided_by": null,
        "decided_at": "2026-10-01T12:00:00.000Z"
      },
      "card_disputes": [
        {
          "object": null,
          "id": null,
          "order": null,
          "stripe_dispute": null,
          "amount": null,
          "currency": null,
          "reason": null,
          "status": null,
          "created_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.
stage	one of: evidence, awaiting_decision, decided, in query
order	string, in query

returns 200, dispute list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of dispute
data[].objectrequired	one of: dispute
data[].idrequired	string
data[].orderrequired	string
data[].kindrequired	one of: claimed_order, completed_order
data[].opened_byrequired	one of: buyer, seller
data[].openerrequired	string
data[].reasonrequired	string or null	Null once the opener's data is erased.
data[].stagerequired	one of: evidence, awaiting_decision, decided
data[].evidence_due_atrequired	timestamp
data[].decision_due_atrequired	timestamp or null
data[].overduerequired	boolean	True once the decision time limit has passed with no decision.
data[].evidence_countrequired	integer	Pieces of evidence given so far.
data[].decisionrequired	dispute decision or null
data[].decision.againstrequired	one of: buyer, seller
data[].decision.outcomerequired	one of: claim_upheld, claim_rejected, decided	`decided` for a dispute on a completed order, which has no claim to uphold.
data[].decision.refund_amountrequired	integer or null	Refunded to the buyer by this decision. Null with payments off.
data[].decision.noterequired	string
data[].decision.decided_byrequired	string or null
data[].decision.decided_atrequired	timestamp
data[].card_disputesrequired	array of card dispute	Card disputes on the same order, linked here but separate.
data[].card_disputes[].objectrequired	one of: card_dispute
data[].card_disputes[].idrequired	string
data[].card_disputes[].orderrequired	string
data[].card_disputes[].stripe_disputerequired	string	The dispute's id on your Stripe account.
data[].card_disputes[].amountrequired	integer
data[].card_disputes[].currencyrequired	string
data[].card_disputes[].reasonrequired	string
data[].card_disputes[].statusrequired	string	Stripe's status, such as needs_response, won, or lost.
data[].card_disputes[].created_atrequired	timestamp
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.

GET /v1/disputes/{id}

Retrieve a dispute

secret key only

GET /v1/disputes/{id}request

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

200 example response, dispute

{
  "object": "dispute",
  "id": "dsp_034XtPDs7UJ0TXzTsdaHZa",
  "order": "string",
  "kind": "claimed_order",
  "opened_by": "buyer",
  "opener": "string",
  "reason": null,
  "stage": "evidence",
  "evidence_due_at": "2026-10-01T12:00:00.000Z",
  "decision_due_at": null,
  "overdue": false,
  "evidence_count": 0,
  "decision": {
    "against": "buyer",
    "outcome": "claim_upheld",
    "refund_amount": null,
    "note": "string",
    "decided_by": null,
    "decided_at": "2026-10-01T12:00:00.000Z"
  },
  "card_disputes": [
    {
      "object": "card_dispute",
      "id": "cdp_034XtPDs7UJ0TXzTsdaHZa",
      "order": "string",
      "stripe_dispute": "string",
      "amount": 0,
      "currency": "string",
      "reason": "string",
      "status": "string",
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "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, dispute

fields

Response fields
field	type	about
objectrequired	one of: dispute
idrequired	string
orderrequired	string
kindrequired	one of: claimed_order, completed_order
opened_byrequired	one of: buyer, seller
openerrequired	string
reasonrequired	string or null	Null once the opener's data is erased.
stagerequired	one of: evidence, awaiting_decision, decided
evidence_due_atrequired	timestamp
decision_due_atrequired	timestamp or null
overduerequired	boolean	True once the decision time limit has passed with no decision.
evidence_countrequired	integer	Pieces of evidence given so far.
decisionrequired	dispute decision or null
decision.againstrequired	one of: buyer, seller
decision.outcomerequired	one of: claim_upheld, claim_rejected, decided	`decided` for a dispute on a completed order, which has no claim to uphold.
decision.refund_amountrequired	integer or null	Refunded to the buyer by this decision. Null with payments off.
decision.noterequired	string
decision.decided_byrequired	string or null
decision.decided_atrequired	timestamp
card_disputesrequired	array of card dispute	Card disputes on the same order, linked here but separate.
card_disputes[].objectrequired	one of: card_dispute
card_disputes[].idrequired	string
card_disputes[].orderrequired	string
card_disputes[].stripe_disputerequired	string	The dispute's id on your Stripe account.
card_disputes[].amountrequired	integer
card_disputes[].currencyrequired	string
card_disputes[].reasonrequired	string
card_disputes[].statusrequired	string	Stripe's status, such as needs_response, won, or lost.
card_disputes[].created_atrequired	timestamp
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/disputes/{id}/evidence

A dispute's evidence, oldest first

secret key only

GET /v1/disputes/{id}/evidencerequest

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

200 example response, dispute evidence list

{
  "object": "list",
  "data": [
    {
      "object": "dispute_evidence",
      "id": "dev_034XtPDs7UJ0TXzTsdaHZa",
      "dispute": "string",
      "party": "buyer",
      "author": "string",
      "body": null,
      "links": [
        "string"
      ],
      "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, dispute evidence list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of dispute evidence
data[].objectrequired	one of: dispute_evidence
data[].idrequired	string
data[].disputerequired	string
data[].partyrequired	one of: buyer, seller
data[].authorrequired	string
data[].bodyrequired	string or null
data[].linksrequired	array of string
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/disputes/{id}/evidence

Add evidence from one side

Only while the dispute is in its evidence stage.

secret key only

POST /v1/disputes/{id}/evidencerequest

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

201 example response, dispute evidence

{
  "object": "dispute_evidence",
  "id": "dev_034XtPDs7UJ0TXzTsdaHZa",
  "dispute": "string",
  "party": "buyer",
  "author": "string",
  "body": null,
  "links": [
    "string"
  ],
  "created_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, add evidence

Request body
field	type	about
actorrequired	string	The buyer or seller giving evidence.
bodyrequired	string	up to 10000 characters
links	array of string	Links to files the party provided, such as photos you store. HTTPS only.up to 5 items

returns 201, dispute evidence

fields

Response fields
field	type	about
objectrequired	one of: dispute_evidence
idrequired	string
disputerequired	string
partyrequired	one of: buyer, seller
authorrequired	string
bodyrequired	string or null
linksrequired	array of string
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.

POST /v1/disputes/{id}/close_evidence

End the evidence stage early

secret key only

POST /v1/disputes/{id}/close_evidencerequest

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

200 example response, dispute

{
  "object": "dispute",
  "id": "dsp_034XtPDs7UJ0TXzTsdaHZa",
  "order": "string",
  "kind": "claimed_order",
  "opened_by": "buyer",
  "opener": "string",
  "reason": null,
  "stage": "evidence",
  "evidence_due_at": "2026-10-01T12:00:00.000Z",
  "decision_due_at": null,
  "overdue": false,
  "evidence_count": 0,
  "decision": {
    "against": "buyer",
    "outcome": "claim_upheld",
    "refund_amount": null,
    "note": "string",
    "decided_by": null,
    "decided_at": "2026-10-01T12:00:00.000Z"
  },
  "card_disputes": [
    {
      "object": "card_dispute",
      "id": "cdp_034XtPDs7UJ0TXzTsdaHZa",
      "order": "string",
      "stripe_dispute": "string",
      "amount": 0,
      "currency": "string",
      "reason": "string",
      "status": "string",
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "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, dispute

fields

Response fields
field	type	about
objectrequired	one of: dispute
idrequired	string
orderrequired	string
kindrequired	one of: claimed_order, completed_order
opened_byrequired	one of: buyer, seller
openerrequired	string
reasonrequired	string or null	Null once the opener's data is erased.
stagerequired	one of: evidence, awaiting_decision, decided
evidence_due_atrequired	timestamp
decision_due_atrequired	timestamp or null
overduerequired	boolean	True once the decision time limit has passed with no decision.
evidence_countrequired	integer	Pieces of evidence given so far.
decisionrequired	dispute decision or null
decision.againstrequired	one of: buyer, seller
decision.outcomerequired	one of: claim_upheld, claim_rejected, decided	`decided` for a dispute on a completed order, which has no claim to uphold.
decision.refund_amountrequired	integer or null	Refunded to the buyer by this decision. Null with payments off.
decision.noterequired	string
decision.decided_byrequired	string or null
decision.decided_atrequired	timestamp
card_disputesrequired	array of card dispute	Card disputes on the same order, linked here but separate.
card_disputes[].objectrequired	one of: card_dispute
card_disputes[].idrequired	string
card_disputes[].orderrequired	string
card_disputes[].stripe_disputerequired	string	The dispute's id on your Stripe account.
card_disputes[].amountrequired	integer
card_disputes[].currencyrequired	string
card_disputes[].reasonrequired	string
card_disputes[].statusrequired	string	Stripe's status, such as needs_response, won, or lost.
card_disputes[].created_atrequired	timestamp
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.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/disputes/{id}/decide

Decide a dispute

Your team's decision: who it went against, in writing, and with payments on, how much goes back to the buyer. On a claimed order, deciding against the party who disputed upholds the claim and completes the order; deciding against the claimant cancels it.

secret key only

POST /v1/disputes/{id}/deciderequest

curl -X POST https://api.marketsdk.com/v1/disputes/{id}/decide \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"against":"buyer","note":"string"}'

200 example response, dispute

{
  "object": "dispute",
  "id": "dsp_034XtPDs7UJ0TXzTsdaHZa",
  "order": "string",
  "kind": "claimed_order",
  "opened_by": "buyer",
  "opener": "string",
  "reason": null,
  "stage": "evidence",
  "evidence_due_at": "2026-10-01T12:00:00.000Z",
  "decision_due_at": null,
  "overdue": false,
  "evidence_count": 0,
  "decision": {
    "against": "buyer",
    "outcome": "claim_upheld",
    "refund_amount": null,
    "note": "string",
    "decided_by": null,
    "decided_at": "2026-10-01T12:00:00.000Z"
  },
  "card_disputes": [
    {
      "object": "card_dispute",
      "id": "cdp_034XtPDs7UJ0TXzTsdaHZa",
      "order": "string",
      "stripe_dispute": "string",
      "amount": 0,
      "currency": "string",
      "reason": "string",
      "status": "string",
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "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, decide dispute

Request body
field	type	about
againstrequired	one of: buyer, seller	Who the decision went against. They get a dispute_lost reputation event; the other party gets dispute_won.
noterequired	string	The written decision, kept with the dispute.up to 5000 characters
refund_amount	integer	Payments on only. Minor units to refund to the buyer; the rest goes to the seller. Defaults: a claimed order whose claim is upheld refunds nothing; one whose claim is rejected refunds everything; a dispute on a completed order refunds nothing.min 0
decided_by	string	Who on your team decided, for the record. Up to 200 characters.up to 200 characters

returns 200, dispute

fields

Response fields
field	type	about
objectrequired	one of: dispute
idrequired	string
orderrequired	string
kindrequired	one of: claimed_order, completed_order
opened_byrequired	one of: buyer, seller
openerrequired	string
reasonrequired	string or null	Null once the opener's data is erased.
stagerequired	one of: evidence, awaiting_decision, decided
evidence_due_atrequired	timestamp
decision_due_atrequired	timestamp or null
overduerequired	boolean	True once the decision time limit has passed with no decision.
evidence_countrequired	integer	Pieces of evidence given so far.
decisionrequired	dispute decision or null
decision.againstrequired	one of: buyer, seller
decision.outcomerequired	one of: claim_upheld, claim_rejected, decided	`decided` for a dispute on a completed order, which has no claim to uphold.
decision.refund_amountrequired	integer or null	Refunded to the buyer by this decision. Null with payments off.
decision.noterequired	string
decision.decided_byrequired	string or null
decision.decided_atrequired	timestamp
card_disputesrequired	array of card dispute	Card disputes on the same order, linked here but separate.
card_disputes[].objectrequired	one of: card_dispute
card_disputes[].idrequired	string
card_disputes[].orderrequired	string
card_disputes[].stripe_disputerequired	string	The dispute's id on your Stripe account.
card_disputes[].amountrequired	integer
card_disputes[].currencyrequired	string
card_disputes[].reasonrequired	string
card_disputes[].statusrequired	string	Stripe's status, such as needs_response, won, or lost.
card_disputes[].created_atrequired	timestamp
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.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/orders/{id}/disputes

Dispute an order

On a claimed order, by the party who did not claim: the order becomes disputed. On a completed order, by either party inside the dispute window: the order stays completed.

secret key only

POST /v1/orders/{id}/disputesrequest

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

201 example response, dispute

{
  "object": "dispute",
  "id": "dsp_034XtPDs7UJ0TXzTsdaHZa",
  "order": "string",
  "kind": "claimed_order",
  "opened_by": "buyer",
  "opener": "string",
  "reason": null,
  "stage": "evidence",
  "evidence_due_at": "2026-10-01T12:00:00.000Z",
  "decision_due_at": null,
  "overdue": false,
  "evidence_count": 0,
  "decision": {
    "against": "buyer",
    "outcome": "claim_upheld",
    "refund_amount": null,
    "note": "string",
    "decided_by": null,
    "decided_at": "2026-10-01T12:00:00.000Z"
  },
  "card_disputes": [
    {
      "object": "card_dispute",
      "id": "cdp_034XtPDs7UJ0TXzTsdaHZa",
      "order": "string",
      "stripe_dispute": "string",
      "amount": 0,
      "currency": "string",
      "reason": "string",
      "status": "string",
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "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, open dispute

Request body
field	type	about
actorrequired	string	The buyer or seller opening the dispute.
reasonrequired	string	What went wrong, in their words.up to 2000 characters
metadata	object of strings

returns 201, dispute

fields

Response fields
field	type	about
objectrequired	one of: dispute
idrequired	string
orderrequired	string
kindrequired	one of: claimed_order, completed_order
opened_byrequired	one of: buyer, seller
openerrequired	string
reasonrequired	string or null	Null once the opener's data is erased.
stagerequired	one of: evidence, awaiting_decision, decided
evidence_due_atrequired	timestamp
decision_due_atrequired	timestamp or null
overduerequired	boolean	True once the decision time limit has passed with no decision.
evidence_countrequired	integer	Pieces of evidence given so far.
decisionrequired	dispute decision or null
decision.againstrequired	one of: buyer, seller
decision.outcomerequired	one of: claim_upheld, claim_rejected, decided	`decided` for a dispute on a completed order, which has no claim to uphold.
decision.refund_amountrequired	integer or null	Refunded to the buyer by this decision. Null with payments off.
decision.noterequired	string
decision.decided_byrequired	string or null
decision.decided_atrequired	timestamp
card_disputesrequired	array of card dispute	Card disputes on the same order, linked here but separate.
card_disputes[].objectrequired	one of: card_dispute
card_disputes[].idrequired	string
card_disputes[].orderrequired	string
card_disputes[].stripe_disputerequired	string	The dispute's id on your Stripe account.
card_disputes[].amountrequired	integer
card_disputes[].currencyrequired	string
card_disputes[].reasonrequired	string
card_disputes[].statusrequired	string	Stripe's status, such as needs_response, won, or lost.
card_disputes[].created_atrequired	timestamp
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.