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. For details and migration steps, visit our migration guide.
Dispute
shopify_payments_payouts, shopify_payments.Disputes occur when a buyer questions the legitimacy of a charge with their financial institution.
Endpoints
- get/admin/api/latest/shopify_
payments/disputes. json?initiated_ at=2013-05-03 Return a list of all disputes - get/admin/api/latest/shopify_
payments/disputes/{dispute_ id}. json Return a single dispute
The Dispute resource
Properties
The ID of the dispute.
The ID of the order that the dispute belongs to.
Whether the dispute is still in the inquiry phase or has turned into a chargeback. Valid values:
Show type properties
- inquiry: The dispute is in the inquiry phase.
- chargeback: The dispute has turned into a chargeback.
The ISO 4217 currency code of the dispute amount.
The total amount disputed by the cardholder.
The reason of the dispute provided by the cardholder's bank. Valid values:
Show reason properties
- 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.
The reason for the dispute provided by the cardholder's bank.
The current state of the dispute. Valid values:
Show status properties
- 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.
The deadline for evidence submission.
"The date and time (ISO 8601 format) when
evidence was sent. Returns null if evidence has not yet been sent.
The date and time (ISO 8601 format) when
this dispute was resolved. Returns null if the dispute is not yet resolved.
The Dispute resource
Anchor to GET request, Return a list of all disputesgetReturn a list of all disputes
Retrieve all disputes ordered by initiated_at date and time (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.
Return only disputes with the specified initiated_at date (ISO 8601 format).
Return only disputes before the specified ID.
Return only disputes after the specified ID.
Return only disputes with the specified status.
Retrieve all disputes initiated on 2013-05-03
Retrieve all disputes initiated on 2013-05-03
Return only disputes with the specified initiated_at date (ISO 8601 format).
Retrieve all disputes ordered newest to oldest
Retrieve all disputes ordered newest to oldest
Retrieve all won disputes
Retrieve all won disputes
Return only disputes with the specified status.
/admin/api/2025-07/shopify_
Response
Anchor to GET request, Return a single disputegetReturn a single dispute
Retrieves a single dispute by ID.
Retrieves a single dispute by ID
Retrieves a single dispute by ID