The Dispute object v1

Attributes

idstring
Unique identifier for the object.

amountinteger
Disputed amount. Usually the amount of the charge, but it can differ (usually because of currency fluctuation or because only part of the order is disputed).

chargestringExpandable
ID of the charge that’s disputed.

currencyenum
Three-letter ISO currency code, in lowercase. Must be a supported currency.

evidenceobject
Evidence provided to respond to a dispute. Updating any field in the hash submits all fields in the hash for review.

metadatamap
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

payment_intentnullable stringExpandable
ID of the PaymentIntent that’s disputed.

reasonstring
Reason given by cardholder for dispute. Possible values are bank_cannot_process, check_returned, credit_not_processed, customer_initiated, debit_not_authorized, duplicate, fraudulent, general, incorrect_account_details, insufficient_funds, noncompliant, product_not_received, product_unacceptable, subscription_canceled, or unrecognized. Learn more about dispute reasons.

statusenum

The current status of a dispute. Possible values include:warning_needs_response, warning_under_review, warning_closed, needs_response, under_review, appeal_needs_response, appeal_under_review, won, lost, or prevented.

Possible enum values

appeal_needs_response

A dispute that requires a response to an appeal.

appeal_under_review

A dispute under review after appeal evidence is submitted.

lost

A dispute resolved in the customer’s favor.

needs_response

A dispute that requires a response.

prevented

A dispute that was prevented from becoming a formal chargeback.

under_review

A dispute under review after evidence submission.

warning_closed

An inquiry closed without becoming a formal dispute.

warning_needs_response

An inquiry that requires a response.

warning_under_review

An inquiry under review after evidence submission.

won

A dispute resolved in the merchant’s favor.

More attributes

objectstring, value is "dispute"

balance_transactionsarray of objects

createdtimestamp

enhanced_eligibility_typesarray of enums

evidence_detailsobject

intended_submission_methodnullable enum

is_charge_refundableboolean

livemodeboolean

payment_method_detailsnullable object

The Dispute object

{
  "id": "du_1MtJUT2eZvKYlo2CNaw2HvEv",
  "object": "dispute",
  "amount": 1000,
  "balance_transactions": [],
  "charge": "ch_1AZtxr2eZvKYlo2CJDX8whov",
  "created": 1680651737,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1682294399,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": true,
  "livemode": false,
  "metadata": {},
  "payment_intent": null,
  "reason": "general",
  "status": "warning_needs_response"
}

Update a dispute v1

POST /v1/disputes/:id

When you get a dispute, contacting your customer is always the best first step. If that doesn’t work, you can submit evidence to help us resolve the dispute in your favor. You can do this in your dashboard, but if you prefer, you can use the API to submit evidence programmatically.

Depending on your dispute type, different evidence fields will give you a better chance of winning your dispute. To figure out which evidence fields to provide, see our guide to dispute types.

Parameters

idstringRequired
Unique identifier for the object.

evidenceobject
Evidence to upload, to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review. The combined character count of all fields is limited to 150,000.

intended_submission_methodenum

Intended submission method for the dispute.

Possible enum values

manual

You’ll submit the manual packet if you upload evidence and won’t ever use Smart Disputes to respond to the dispute.

prefer_manual

You’ll submit the manual packet if you upload evidence, but use Smart Disputes if you have no evidence to add to the dispute response.

prefer_smart_disputes

You’ll let Smart Disputes submit the dispute response if it detects Stripe evidence, but use the manual packet otherwise.

smart_disputes

You’ll let Smart Disputes submit the dispute response if it detects Stripe evidence, and won’t use the manual packet.

metadatamap
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

submitboolean
Whether to immediately submit evidence to the bank. If false, evidence is staged on the dispute. Staged evidence is visible in the API and Dashboard, and can be submitted to the bank by making another request with this attribute set to true (the default).

Returns

Returns the dispute object.

curl https://api.stripe.com/v1/disputes/{{DISPUTE_ID}} \
  -u "sk_test_...sk_test_...:" \
  -H "Stripe-Version: 2026-10-28.endive" \
  -d "metadata[order_id]=6735"

Response

{
  "id": "du_1MtJUT2eZvKYlo2CNaw2HvEv",
  "object": "dispute",
  "amount": 1000,
  "balance_transactions": [],
  "charge": "ch_1AZtxr2eZvKYlo2CJDX8whov",
  "created": 1680651737,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1682294399,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": true,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "payment_intent": null,
  "reason": "general",
  "status": "warning_needs_response"
}

Retrieve a dispute v1

GET /v1/disputes/:id

Retrieves the dispute with the given ID.

Parameters

idstringRequired
Unique identifier for the object.

Returns

Returns a dispute if a valid dispute ID was provided. Raises an error otherwise.

curl https://api.stripe.com/v1/disputes/{{DISPUTE_ID}} \
  -u "sk_test_...sk_test_...:" \
  -H "Stripe-Version: 2026-10-28.endive"

Response

{
  "id": "du_1MtJUT2eZvKYlo2CNaw2HvEv",
  "object": "dispute",
  "amount": 1000,
  "balance_transactions": [],
  "charge": "ch_1AZtxr2eZvKYlo2CJDX8whov",
  "created": 1680651737,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1682294399,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": true,
  "livemode": false,
  "metadata": {},
  "payment_intent": null,
  "reason": "general",
  "status": "warning_needs_response"
}

The Dispute object v1

Attributes

idstring

amountinteger

chargestringExpandable

currencyenum

evidenceobject

metadatamap

payment_intentnullable stringExpandable

reasonstring

statusenum

More attributesExpand all

objectstring, value is "dispute"

balance_transactionsarray of objects

createdtimestamp

enhanced_eligibility_typesarray of enums

evidence_detailsobject

intended_submission_methodnullable enum

is_charge_refundableboolean

livemodeboolean

payment_method_detailsnullable object

Update a dispute v1

Parameters

idstringRequired

evidenceobject

intended_submission_methodenum

metadatamap

submitboolean

Returns

Retrieve a dispute v1

Parameters

idstringRequired

Returns

More attributes