Update a dispute
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
- evidence object 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.
- metadata map 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. - submit boolean 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 totrue(the default).
Returns
Returns the dispute object.
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
GET / v1 / disputes /:id
Retrieves the dispute with the given ID.
Parameters
No parameters.
Returns
Returns a dispute if a valid dispute ID was provided. Raises an error otherwise.
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"}
List all disputes
GET / v1 / disputes
Returns a list of your disputes.
Parameters
- charge string Only return disputes associated to the charge specified by this charge ID.
- payment _ intent string Only return disputes associated to the PaymentIntent specified by this PaymentIntent ID.
More parameters
- created object
- ending _ before string
- limit integer
- starting _ after string
Returns
A dictionary with a data property that contains an array of up to limit disputes, starting after dispute starting_after. Each entry in the array is a separate dispute object. If no more disputes are available, the resulting array will be empty.
Response
{ "object": "list", "url": "/v1/disputes", "has_more": false, "data": [ { "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" } ]}