---
title: Dispute
description: Get information regarding Shopify Payments disputes.
api_version: 2026-07
source_url:
  html: 'https://shopify.dev/docs/api/admin-rest/latest/resources/dispute'
  md: 'https://shopify.dev/docs/api/admin-rest/latest/resources/dispute.md'
api_name: admin-rest
api_type: rest
---

The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql). For details and migration steps, visit our [migration guide](https://shopify.dev/docs/apps/build/graphql/migrate).

# Dispute

**Requires ANY of the following access scopes: \`shopify\_payments\_payouts\`, \`shopify\_payments\`.:**

Disputes occur when a buyer questions the legitimacy of a charge with their financial institution.

\#

## Endpoints

* [get](https://shopify.dev/docs/api/admin-rest/latest/resources/dispute.md#get-shopify-payments-disputes?initiated-at=2013-05-03)

  [/admin/api/latest/shopify\_​payments/disputes.​json?initiated\_​at=2013-05-03](https://shopify.dev/docs/api/admin-rest/latest/resources/dispute.md#get-shopify-payments-disputes?initiated-at=2013-05-03)

  Return a list of all disputes

  [shopifyPaymentsAccount](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyPaymentsAccount?example=return-a-list-of-all-disputes)

* [get](https://shopify.dev/docs/api/admin-rest/latest/resources/dispute.md#get-shopify-payments-disputes-dispute-id)

  [/admin/api/latest/shopify\_​payments/disputes/{dispute\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/dispute.md#get-shopify-payments-disputes-dispute-id)

  Return a single dispute

  [dispute](https://shopify.dev/docs/api/admin-graphql/latest/queries/dispute?example=return-a-single-dispute)

***

## The Dispute resource

### Properties

***

id

->[id](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsDispute#field-ShopifyPaymentsDispute.fields.id)

The ID of the dispute.

***

order\_id

->[id](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order#field-Order.fields.id)

The ID of the order that the dispute belongs to.

***

type

->[type](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsDispute#field-ShopifyPaymentsDispute.fields.type)

Whether the dispute is still in the inquiry phase or has turned into a chargeback. Valid values:

* **inquiry**: The dispute is in the inquiry phase.
* **chargeback**: The dispute has turned into a chargeback.

***

currency

->[currencyCode](https://shopify.dev/docs/api/admin-graphql/latest/objects/MoneyV2#field-MoneyV2.fields.currencyCode)

The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the dispute amount.

***

amount

->[amount](https://shopify.dev/docs/api/admin-graphql/latest/objects/MoneyV2#field-MoneyV2.fields.amount)

The total amount disputed by the cardholder.

***

reason

->[reason](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsDisputeReasonDetails#field-ShopifyPaymentsDisputeReasonDetails.fields.reason)

The reason of the dispute provided by the cardholder's bank. Valid values:

* **bank\_not\_process**: The customer's bank cannot process the charge.
* **credit\_not\_processed**: The customer claims that the purchased product was returned or the transaction was otherwise canceled, but the merchant have not yet provided a refund or credit.
* **customer\_initiated**: The customer initiated the dispute, so the merchant should contact the customer for additional details to find out why the payment was disputed.
* **debit\_not\_authorized**: The customer's bank cannot proceed with the debit since it has not been authorized.
* **duplicate**: The customer claims they were charged multiple times for the same product or service.
* **fraudulent**: The cardholder claims that they didn't authorize the payment.
* **general**: The dispute is uncategorized, so the merchant should contact the customer for additional details to find out why the payment was disputed.
* **incorrect\_account\_details**: The customer account associated with the purchase is incorrect.
* **insufficient\_funds**: The customer's bank account has insufficient funds.
* **product\_not\_received**: The customer claims they did not receive the products or services purchased.
* **product\_unacceptable**: The product or service was received but was defective, damaged, or not as described.
* **subscription\_canceled**: The customer claims that the merchant continued to charge them after a subscription was canceled.
* **unrecognized**: The customer doesn't recognize the payment appearing on their card statement.

***

network\_reason\_code

**string**

->[networkReasonCode](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsDisputeReasonDetails#field-ShopifyPaymentsDisputeReasonDetails.fields.networkReasonCode)

The reason for the dispute provided by the cardholder's bank.

***

status

->[status](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsDispute#field-ShopifyPaymentsDispute.fields.status)

The current state of the dispute. Valid values:

* **needs\_response**: The dispute has been open and needs an evidence submission.
* **under\_review**: The evidence has been submitted and is being reviewed by the cardholder's bank.
* **charge\_refunded**: The merchant refunded the inquiry amount.
* **accepted**: The merchant has accepted the dispute as being valid.
* **won**: The cardholder's bank reached a final decision in the merchant's favor.
* **lost**: The cardholder's bank reached a final decision in the buyer's favor.

***

evidence\_due\_by

->[evidenceDueBy](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsDispute#field-ShopifyPaymentsDispute.fields.evidenceDueBy)

The deadline for evidence submission.

***

evidence\_sent\_on

->[evidenceSentOn](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsDispute#field-ShopifyPaymentsDispute.fields.evidenceSentOn)

"The date and time ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format) when evidence was sent. Returns `null` if evidence has not yet been sent.

***

finalized\_on

->[finalizedOn](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsDispute#field-ShopifyPaymentsDispute.fields.finalizedOn)

The date and time ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format) when this dispute was resolved. Returns `null` if the dispute is not yet resolved.

***

{}

## The Dispute resource

```json
{
  "id": 54534554564,
  "order_id": 450789469,
  "type": "inquiry",
  "currency": "USD",
  "amount": "102.53",
  "reason": "fraudulent",
  "network_reason_code": "4840",
  "status": "under_review",
  "evidence_due_by": "2018-01-10T11:00:00-05:00",
  "evidence_sent_on": "2018-01-09T11:00:00-05:00",
  "finalized_on": "2018-03-10T11:00:00-05:00"
}
```

***

## getReturn a list of all disputes

[shopifyPaymentsAccount](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyPaymentsAccount?example=return-a-list-of-all-disputes)

Retrieve all disputes ordered by `initiated_at` date and time ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format), with the most recent being first. **Note:** This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to [Make paginated requests to the REST Admin API](https://shopify.dev/api/usage/pagination-rest).

### Parameters

***

api\_version

**string**

**required**

***

initiated\_at

Return only disputes with the specified `initiated_at` date ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).

***

last\_id

Return only disputes before the specified ID.

***

since\_id

Return only disputes after the specified ID.

***

status

Return only disputes with the specified status.

***

### Examples

### Retrieve all disputes initiated on 2013-05-03

### Query parameters

initiated\_​at=​2013-05-03

Return only disputes with the specified `initiated_at` date ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).

### Retrieve all disputes ordered newest to oldest

### Retrieve all won disputes

### Query parameters

status=​won

Return only disputes with the specified status.

get

## /admin/api/2026-07/shopify\_​payments/disputes.​json?initiated\_​at=​2013-05-03

```bash
curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/shopify_payments/disputes.json?initiated_at=2013-05-03" \
-H "X-Shopify-Access-Token: {access_token}"
```

{}

## Response

JSON

```json
HTTP/1.1 200 OK
{
  "disputes": [
    {
      "id": 1052608616,
      "order_id": null,
      "type": "chargeback",
      "amount": "100.00",
      "currency": "USD",
      "reason": "fraudulent",
      "network_reason_code": "4827",
      "status": "won",
      "evidence_due_by": "2013-07-03T19:00:00-04:00",
      "evidence_sent_on": "2013-07-04T07:00:00-04:00",
      "finalized_on": null,
      "initiated_at": "2013-05-03T20:00:00-04:00"
    },
    {
      "id": 815713555,
      "order_id": 625362839,
      "type": "chargeback",
      "amount": "11.50",
      "currency": "USD",
      "reason": "credit_not_processed",
      "network_reason_code": "4827",
      "status": "needs_response",
      "evidence_due_by": "2099-12-29T19:00:00-05:00",
      "evidence_sent_on": null,
      "finalized_on": null,
      "initiated_at": "2013-05-03T20:00:00-04:00"
    },
    {
      "id": 782360659,
      "order_id": 625362839,
      "type": "chargeback",
      "amount": "11.50",
```

### examples

* #### Retrieve all disputes initiated on 2013-05-03

  #####

  ```curl
  curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/shopify_payments/disputes.json?initiated_at=2013-05-03" \
  -H "X-Shopify-Access-Token: {access_token}"
  ```

  #### response

  ```json
  HTTP/1.1 200 OK{"disputes":[{"id":1052608616,"order_id":null,"type":"chargeback","amount":"100.00","currency":"USD","reason":"fraudulent","network_reason_code":"4827","status":"won","evidence_due_by":"2013-07-03T19:00:00-04:00","evidence_sent_on":"2013-07-04T07:00:00-04:00","finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":815713555,"order_id":625362839,"type":"chargeback","amount":"11.50","currency":"USD","reason":"credit_not_processed","network_reason_code":"4827","status":"needs_response","evidence_due_by":"2099-12-29T19:00:00-05:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":782360659,"order_id":625362839,"type":"chargeback","amount":"11.50","currency":"USD","reason":"fraudulent","network_reason_code":"4827","status":"won","evidence_due_by":"2013-07-03T19:00:00-04:00","evidence_sent_on":"2013-07-04T07:00:00-04:00","finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":670893524,"order_id":625362839,"type":"inquiry","amount":"11.50","currency":"USD","reason":"fraudulent","network_reason_code":"4827","status":"needs_response","evidence_due_by":null,"evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":598735659,"order_id":625362839,"type":"chargeback","amount":"11.50","currency":"USD","reason":"fraudulent","network_reason_code":"4827","status":"needs_response","evidence_due_by":"2099-12-29T19:00:00-05:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":428123260,"order_id":625362839,"type":"chargeback","amount":"11.50","currency":"USD","reason":"debit_not_authorized","network_reason_code":"R10","status":"lost","evidence_due_by":"2099-12-29T19:00:00-05:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":297752803,"order_id":625362839,"type":"chargeback","amount":"100.00","currency":"USD","reason":"fraudulent","network_reason_code":"4827","status":"lost","evidence_due_by":"2099-12-29T19:00:00-05:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":257169523,"order_id":625362839,"type":"chargeback","amount":"11.50","currency":"USD","reason":"fraudulent","network_reason_code":"4827","status":"needs_response","evidence_due_by":"2099-12-29T19:00:00-05:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":172886728,"order_id":625362839,"type":"chargeback","amount":"11.50","currency":"USD","reason":"insufficient_funds","network_reason_code":"R07","status":"lost","evidence_due_by":"2099-12-29T19:00:00-05:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":85190714,"order_id":625362839,"type":"chargeback","amount":"11.50","currency":"USD","reason":"fraudulent","network_reason_code":"4827","status":"under_review","evidence_due_by":"2099-12-29T19:00:00-05:00","evidence_sent_on":"2099-12-30T19:00:00-05:00","finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":51858708,"order_id":1039068725,"type":"inquiry","amount":"31.33","currency":"EUR","reason":"fraudulent","network_reason_code":"4827","status":"needs_response","evidence_due_by":null,"evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":46484353,"order_id":625362839,"type":"chargeback","amount":"100.00","currency":"USD","reason":"fraudulent","network_reason_code":"4827","status":"lost","evidence_due_by":"2099-12-29T19:00:00-05:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"},{"id":35982383,"order_id":625362839,"type":"chargeback","amount":"11.50","currency":"USD","reason":"subscription_canceled","network_reason_code":"4827","status":"needs_response","evidence_due_by":"2099-12-29T19:00:00-05:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"}]}
  ```

* #### Retrieve all disputes ordered newest to oldest

  #####

  ```curl
  curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/shopify_payments/disputes.json" \
  -H "X-Shopify-Access-Token: {access_token}"
  ```

* #### Retrieve all won disputes

  #####

  ```curl
  curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/shopify_payments/disputes.json?status=won" \
  -H "X-Shopify-Access-Token: {access_token}"
  ```

***

## getReturn a single dispute

[dispute](https://shopify.dev/docs/api/admin-graphql/latest/queries/dispute?example=return-a-single-dispute)

Retrieves a single dispute by ID.

### Parameters

***

api\_version

**string**

**required**

***

dispute\_id

**string**

**required**

***

### Examples

### Retrieves a single dispute by ID

### Path parameters

dispute\_​id=​598735659

**string**

**required**

get

## /admin/api/2026-07/shopify\_​payments/disputes/598735659.​json

```bash
curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/shopify_payments/disputes/598735659.json" \
-H "X-Shopify-Access-Token: {access_token}"
```

{}

## Response

JSON

```json
HTTP/1.1 200 OK
{
  "dispute": {
    "id": 598735659,
    "order_id": 625362839,
    "type": "chargeback",
    "amount": "11.50",
    "currency": "USD",
    "reason": "fraudulent",
    "network_reason_code": "4827",
    "status": "needs_response",
    "evidence_due_by": "2099-12-29T19:00:00-05:00",
    "evidence_sent_on": null,
    "finalized_on": null,
    "initiated_at": "2013-05-03T20:00:00-04:00"
  }
}
```

### examples

* #### Retrieves a single dispute by ID

  #####

  ```curl
  curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/shopify_payments/disputes/598735659.json" \
  -H "X-Shopify-Access-Token: {access_token}"
  ```

  #### response

  ```json
  HTTP/1.1 200 OK{"dispute":{"id":598735659,"order_id":625362839,"type":"chargeback","amount":"11.50","currency":"USD","reason":"fraudulent","network_reason_code":"4827","status":"needs_response","evidence_due_by":"2099-12-29T19:00:00-05:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"}}
  ```