# Dispute

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

## Resource Properties

### Dispute

* id: The ID of the dispute.
  * Type: x-string
  * Example: 54534554564
* order_id: The ID of the order that the dispute belongs to.
  * Type: x-string
  * Example: 450789469
* type:           Whether the dispute is still in the inquiry phase or has turned into a chargeback.
          Valid values:
          <ul>
            <li><strong>inquiry</strong>: The dispute is in the inquiry phase.</li>
            <li><strong>chargeback</strong>: The dispute has turned into a chargeback.</li>
          </ul>

  * Type: x-string
  * Example: "inquiry"
* currency:           The <a href="https://en.wikipedia.org/wiki/ISO_4217">ISO 4217</a> currency code of the dispute amount.

  * Type: x-string
  * Example: "USD"
* amount: The total amount disputed by the cardholder.
  * Type: x-string
  * Example: "102.53"
* reason:           The reason of the dispute provided by the cardholder's bank. Valid values:
          <ul>
            <li><strong>bank_not_process</strong>: The customer's bank cannot process the charge.</li>
            <li>
              <strong>credit_not_processed</strong>: 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.
            </li>
            <li>
              <strong>customer_initiated</strong>: The customer initiated the dispute, so the merchant should contact
              the customer for additional details to find out why the payment was disputed.
            </li>
            <li>
              <strong>debit_not_authorized</strong>: The customer's bank cannot proceed with the debit
              since it has not been authorized.
            </li>
            <li>
              <strong>duplicate</strong>: The customer claims they were charged multiple times
              for the same product or service.
            </li>
            <li><strong>fraudulent</strong>: The cardholder claims that they didn't authorize the payment.</li>
            <li>
              <strong>general</strong>: The dispute is uncategorized, so the merchant should contact the customer for
              additional details to find out why the payment was disputed.
            </li>
            <li>
              <strong>incorrect_account_details</strong>: The customer account associated with the
              purchase is incorrect.
            </li>
            <li><strong>insufficient_funds</strong>: The customer's bank account has insufficient funds.</li>
            <li>
              <strong>product_not_received</strong>: The customer claims they did not receive the products
              or services purchased.
            </li>
            <li>
              <strong>product_unacceptable</strong>: The product or service was received but was defective,
              damaged, or not as described.
            </li>
            <li>
              <strong>subscription_canceled</strong>: The customer claims that the merchant continued to charge them
              after a subscription was canceled.
            </li>
            <li>
              <strong>unrecognized</strong>: The customer doesn't recognize the payment appearing on
              their card statement.
            </li>
          </ul>

  * Type: x-string
  * Example: "fraudulent"
* network_reason_code: The reason for the dispute provided by the cardholder's bank.
  * Type: string
  * Example: "4840"
* status:           The current state of the dispute. Valid values:
          <ul>
            <li><strong>needs_response</strong>: The dispute has been open and needs an evidence submission.</li>
            <li>
              <strong>under_review</strong>: The evidence has been submitted and is being reviewed by the
              cardholder's bank.
            </li>
            <li><strong>charge_refunded</strong>: The merchant refunded the inquiry amount.</li>
            <li><strong>accepted</strong>: The merchant has accepted the dispute as being valid.</li>
            <li><strong>won</strong>: The cardholder's bank reached a final decision in the merchant's favor.</li>
            <li><strong>lost</strong>: The cardholder's bank reached a final decision in the buyer's favor.</li>
          </ul>

  * Type: x-string
  * Example: "under_review"
* evidence_due_by: The deadline for evidence submission.
  * Type: x-string
  * Example: "2018-01-10T11:00:00-05:00"
* evidence_sent_on:           "The date and time (<a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format) when
          evidence was sent. Returns <code>null</code> if evidence has not yet been sent.

  * Type: x-string
  * Example: "2018-01-09T11:00:00-05:00"
* finalized_on:           The date and time (<a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format) when
          this dispute was resolved. Returns <code>null</code> if the dispute is not yet resolved.

  * Type: x-string
  * Example: "2018-03-10T11:00:00-05:00"
## Return a list of all disputes

Retrieve all disputes ordered by <code>initiated_at</code> date and time (<a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format), with the most recent being first.
          <strong>Note:</strong> This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to <a href='/api/usage/pagination-rest'>Make paginated requests to the REST Admin API</a>.

### Endpoint
/admin/api/#{api_version}/shopify_payments/disputes.json?initiated_at=2013-05-03 (GET)

### Parameters
* api_version (required): 
* initiated_at: Return only disputes with the specified <code>initiated_at</code> date (<a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> 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.

### Responses
#### 200
Return a list of all disputes

Examples:
##### Retrieve all disputes initiated on 2013-05-03
Request:
```
GET /admin/api/unstable/shopify_payments/disputes.json
```

Response:
```
HTTP/1.1 200 OK
{"disputes":[]}
```
##### Retrieve all disputes ordered newest to oldest
Request:
```
GET /admin/api/unstable/shopify_payments/disputes.json
```

Response:
```
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":"2024-10-07T20:00:00-04: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":"2024-10-07T20:00:00-04: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":"2024-10-07T20:00:00-04: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":"2024-10-07T20:00:00-04: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":"2024-10-07T20:00:00-04:00","evidence_sent_on":"2024-09-24T20:00:00-04:00","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":"2024-10-07T20:00:00-04: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":"2024-10-07T20:00:00-04:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"}]}
```
##### Retrieve all won disputes
Request:
```
GET /admin/api/unstable/shopify_payments/disputes.json
```

Response:
```
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":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"}]}
```
## Return a single dispute

Retrieves a single dispute by ID.

### Endpoint
/admin/api/#{api_version}/shopify_payments/disputes/{dispute_id}.json (GET)

### Parameters
* api_version (required): 
* dispute_id (required): 

### Responses
#### 200
Return a single dispute

Examples:
##### Retrieves a single dispute by ID
Request:
```
GET /admin/api/unstable/shopify_payments/disputes/598735659.json
```

Response:
```
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":"2024-10-07T20:00:00-04:00","evidence_sent_on":null,"finalized_on":null,"initiated_at":"2013-05-03T20:00:00-04:00"}}
```