Dispute

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

What you can do with Dispute

The Shopify API lets you do the following with the Dispute resource. More detailed versions of these general actions may be available:

Dispute properties

id
"id": 54534554564

The ID of the dispute.

order_id
"order_id": 450789469

The ID of the order that the dispute belongs to.

type
"type": "inquiry"

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
"currency": "USD"

The ISO 4217 currency code of the dispute amount.

amount
"amount": "102.53"

The total amount disputed by the cardholder.

reason
"reason": "fraudulent"

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_cancelled: 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
"network_reason_code": 4840

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

status
"status": "under_review"

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
"evidence_due_by": "2018-01-10T11:00:00-05:00"

The deadline for evidence submission.

evidence_sent_on
"evidence_sent_on": "2018-01-09T11:00:00-05:00"

"The date and time (ISO 8601 format) when evidence was sent. Returns null if evidence has not yet been sent.

finalized_on
"finalized_on": "2018-03-10T11:00:00-05:00"

The date and time (ISO 8601 format) when this dispute was resolved. Returns null if the dispute is not yet resolved.

Endpoints

GET /admin/shopify_payments/disputes.json
Retrieve all disputes ordered by initiated_at date and time, with the most recent being first.
since_id

Return only disputes after the specified ID.

last_id

Return only disputes before the specified ID.

status

Return only disputes with the specified status.

initiated_at

Return only disputes with the specified initiated_at date.

Retrieve all disputes ordered newest to oldest

GET /admin/shopify_payments/disputes.json
View Response
HTTP/1.1 200 OK
{
  "disputes": [
    {
      "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": "2019-01-21T19: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": "2019-01-21T19:00:00-05:00",
      "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": "2019-01-21T19: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": "2019-01-21T19:00:00-05:00",
      "evidence_sent_on": "2019-01-08T19:00:00-05:00",
      "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": "2019-01-21T19:00:00-05:00",
      "evidence_sent_on": null,
      "finalized_on": null,
      "initiated_at": "2013-05-03T20:00:00-04:00"
    }
  ]
}

Retrieve all won disputes

GET /admin/shopify_payments/disputes.json?status=won
View Response
HTTP/1.1 200 OK
{
  "disputes": [
    {
      "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"
    }
  ]
}

Retrieve all disputes initiated on 2013-05-03

GET /admin/shopify_payments/disputes.json?initiated_at=2013-05-03
View Response
HTTP/1.1 200 OK
{
  "disputes": [
    {
      "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": "2019-01-21T19: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": "2019-01-21T19:00:00-05:00",
      "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": "2019-01-21T19: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": "2019-01-21T19:00:00-05:00",
      "evidence_sent_on": "2019-01-08T19:00:00-05:00",
      "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": "2019-01-21T19:00:00-05:00",
      "evidence_sent_on": null,
      "finalized_on": null,
      "initiated_at": "2013-05-03T20:00:00-04:00"
    }
  ]
}
GET /admin/shopify_payments/disputes/598735659.json
Retrieves a single dispute by ID.

Retrieves a single dispute by ID

GET /admin/shopify_payments/disputes/#{dispute_id}.json
View 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": "2019-01-21T19:00:00-05:00",
    "evidence_sent_on": null,
    "finalized_on": null,
    "initiated_at": "2013-05-03T20:00:00-04:00"
  }
}

Sign up for a Partner account to get started.

Sign up