Responding to disputes using the API

Learn how to manage disputes programmatically.

While we recommend most users respond to disputes through the Dashboard, you can programmatically manage disputes using the API. You can be notified of dispute events using webhooks, upload evidence, and respond to disputes. Retrieve a Dispute object to find out more about it:

curl https://api.stripe.com/v1/disputes/dp_6ESimlAcTHbmpA90c9HY \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:
curl https://api.stripe.com/v1/disputes/dp_6ESimlAcTHbmpA90c9HY \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

dispute = Stripe::Dispute.retrieve('dp_6ESimlAcTHbmpA90c9HY')
# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

dispute = Stripe::Dispute.retrieve('dp_6ESimlAcTHbmpA90c9HY')

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

dispute = stripe.Dispute.retrieve('dp_6ESimlAcTHbmpA90c9HY')
# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

dispute = stripe.Dispute.retrieve('dp_6ESimlAcTHbmpA90c9HY')

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$dispute = \Stripe\Dispute::retrieve('dp_6ESimlAcTHbmpA90c9HY');
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$dispute = \Stripe\Dispute::retrieve('dp_6ESimlAcTHbmpA90c9HY');

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Dispute dispute = Dispute.retrieve("dp_6ESimlAcTHbmpA90c9HY");
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Dispute dispute = Dispute.retrieve("dp_6ESimlAcTHbmpA90c9HY");

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const dispute = await stripe.disputes.retrieve('dp_6ESimlAcTHbmpA90c9HY');
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const dispute = await stripe.disputes.retrieve('dp_6ESimlAcTHbmpA90c9HY');

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

dis, _ := dispute.Get("dp_6ESimlAcTHbmpA90c9HY", nil)
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

dis, _ := dispute.Get("dp_6ESimlAcTHbmpA90c9HY", nil)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var service = new DisputeService();
var dispute = service.Get("dp_6ESimlAcTHbmpA90c9HY");
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var service = new DisputeService();
var dispute = service.Get("dp_6ESimlAcTHbmpA90c9HY");

The response contains information about the dispute and any response or evidence that has already been provided.

{
  object: "dispute"
  id: "dp_6ESimlAcTHbmpA90c9HY",
  charge: "ch_5Q4BjL06oPWwho",
  evidence: {
    customer_name: "Jane Austen",
    customer_purchase_ip: "127.0.0.1",
    product_description: "Widget ABC, color: red",
    shipping_tracking_number: "Z01234567890",
    uncategorized_text: "Additional notes and comments",
  },
  evidence_details: {
    due_by: 1403047735,
    submission_count: 1
  }
  ...
}
{
  object: "dispute"
  id: "dp_6ESimlAcTHbmpA90c9HY",
  charge: "ch_5Q4BjL06oPWwho",
  evidence: {
    customer_name: "Jane Austen",
    customer_purchase_ip: "127.0.0.1",
    product_description: "Widget ABC, color: red",
    shipping_tracking_number: "Z01234567890",
    uncategorized_text: "Additional notes and comments",
  },
  evidence_details: {
    due_by: 1403047735,
    submission_count: 1
  }
  ...
}

You update the Dispute object and submit structured evidence within the evidence parameter.

curl https://api.stripe.com/v1/disputes/dp_6ESimlAcTHbmpA90c9HY \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "evidence[customer_email_address]"="email@example.com" \
  -d "evidence[shipping_date]"=2020-09-22 \
  -d "evidence[shipping_documentation]"=file_ag2kvmjEK8af258zEci9
curl https://api.stripe.com/v1/disputes/dp_6ESimlAcTHbmpA90c9HY \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "evidence[customer_email_address]"="email@example.com" \
  -d "evidence[shipping_date]"=2020-09-22 \
  -d "evidence[shipping_documentation]"=file_ag2kvmjEK8af258zEci9

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::Dispute.update(
  'dp_6ESimlAcTHbmpA90c9HY',
  {
    evidence: {
      customer_email_address: 'email@example.com',
      shipping_date: '2020-09-22',
      shipping_documentation: 'file_ag2kvmjEK8af258zEci9',
    },
  }
)
# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::Dispute.update(
  'dp_6ESimlAcTHbmpA90c9HY',
  {
    evidence: {
      customer_email_address: 'email@example.com',
      shipping_date: '2020-09-22',
      shipping_documentation: 'file_ag2kvmjEK8af258zEci9',
    },
  }
)

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.Dispute.modify(
  'dp_6ESimlAcTHbmpA90c9HY',
  evidence={
    'customer_email_address': 'email@example.com',
    'shipping_date': '2020-09-22',
    'shipping_documentation': 'file_ag2kvmjEK8af258zEci9',
  },
)
# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.Dispute.modify(
  'dp_6ESimlAcTHbmpA90c9HY',
  evidence={
    'customer_email_address': 'email@example.com',
    'shipping_date': '2020-09-22',
    'shipping_documentation': 'file_ag2kvmjEK8af258zEci9',
  },
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\Dispute::update(
  'dp_6ESimlAcTHbmpA90c9HY',
  [
    'evidence' => [
      'customer_email_address' => 'email@example.com',
      'shipping_date' => '2020-09-22',
      'shipping_documentation' => 'file_ag2kvmjEK8af258zEci9',
    ],
  ]
);
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\Dispute::update(
  'dp_6ESimlAcTHbmpA90c9HY',
  [
    'evidence' => [
      'customer_email_address' => 'email@example.com',
      'shipping_date' => '2020-09-22',
      'shipping_documentation' => 'file_ag2kvmjEK8af258zEci9',
    ],
  ]
);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Dispute dispute = Dispute.retrieve("dp_6ESimlAcTHbmpA90c9HY");

DisputeUpdateParams params =
  DisputeUpdateParams.builder()
    .setEvidence(
      DisputeUpdateParams.Evidence.builder()
        .setCustomerEmailAddress("email@example.com")
        .setShippingDate("2020-09-22")
        .setShippingDocumentation("file_ag2kvmjEK8af258zEci9")
        .build())
    .build();

dispute.update(params);
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Dispute dispute = Dispute.retrieve("dp_6ESimlAcTHbmpA90c9HY");

DisputeUpdateParams params =
  DisputeUpdateParams.builder()
    .setEvidence(
      DisputeUpdateParams.Evidence.builder()
        .setCustomerEmailAddress("email@example.com")
        .setShippingDate("2020-09-22")
        .setShippingDocumentation("file_ag2kvmjEK8af258zEci9")
        .build())
    .build();

dispute.update(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const dispute = await stripe.disputes.update(
  'dp_6ESimlAcTHbmpA90c9HY',
  {
    evidence: {
      customer_email_address: 'email@example.com',
      shipping_date: '2020-09-22',
      shipping_documentation: 'file_ag2kvmjEK8af258zEci9',
    },
  }
);
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const dispute = await stripe.disputes.update(
  'dp_6ESimlAcTHbmpA90c9HY',
  {
    evidence: {
      customer_email_address: 'email@example.com',
      shipping_date: '2020-09-22',
      shipping_documentation: 'file_ag2kvmjEK8af258zEci9',
    },
  }
);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.DisputeParams{
    Evidence: &stripe.DisputeEvidenceParams{
        CustomerEmailAddress: stripe.String("email@example.com"),
        ShippingDate: stripe.String("2020-09-22"),
        ShippingDocumentation: stripe.String("file_ag2kvmjEK8af258zEci9"),
    },
}
dis, _ := dispute.Update("dp_6ESimlAcTHbmpA90c9HY", params)
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.DisputeParams{
    Evidence: &stripe.DisputeEvidenceParams{
        CustomerEmailAddress: stripe.String("email@example.com"),
        ShippingDate: stripe.String("2020-09-22"),
        ShippingDocumentation: stripe.String("file_ag2kvmjEK8af258zEci9"),
    },
}
dis, _ := dispute.Update("dp_6ESimlAcTHbmpA90c9HY", params)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new DisputeUpdateOptions
{
    Evidence = new DisputeEvidenceOptions
    {
        CustomerEmailAddress = "email@example.com",
        ShippingDate = "2020-09-22",
        ServiceDocumentation = "file_ag2kvmjEK8af258zEci9",
    },
};
var service = new DisputeService();
var dispute = service.Update("dp_6ESimlAcTHbmpA90c9HY", options);
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new DisputeUpdateOptions
{
    Evidence = new DisputeEvidenceOptions
    {
        CustomerEmailAddress = "email@example.com",
        ShippingDate = "2020-09-22",
        ServiceDocumentation = "file_ag2kvmjEK8af258zEci9",
    },
};
var service = new DisputeService();
var dispute = service.Update("dp_6ESimlAcTHbmpA90c9HY", options);

All available fields for the evidence parameter are found by looking at the Dispute evidence object. There are two types of evidence you can provide, depending on the field being updated:

Text-based evidence, such as customer_email and service_date. These types of evidence take a string of text.
File-based evidence, such as service_documentation and customer_communication. These take a file_upload object ID.

You can provide documents or images (e.g., a contract or screenshot) as part of dispute evidence using the File Upload API. A document is first uploaded with the purpose of dispute_evidence, which generates a File_upload object which you can use when submitting evidence. Before uploading a file as dispute evidence, make sure that it meets our recommendations to ensure readability is preserved.

If you’re only interested in submitting a single file or a large amount of plaintext as evidence, use uncategorized_text or uncategorized_file. However, we strongly recommend filling in as many fields as possible so you have the best chance at overturning a dispute.

Next steps

Now that you have learned how to manage disputes programmatically, you may want to learn more about the different reasons for disputes, or move on to related subjects:

If you require assistance with a dispute, please contact Stripe support.