eBay Trading API Call Reference Version 823 Support     Knowledge Base     Forums     All Tutorials     All Code Samples Users Guide Call Reference Making an API Call Tutorials Release Notes

Call Index Field Index Enumeration Index Type Index Deprecated Objects Errors by Number Input Output Detail Controls Samples Change History Top Errors for GetDispute User Notes

GetDispute

Use this call to retrieve the details of a specific dispute. This call retrieves Unpaid Item, Item Not Received, and Significantly Not As Described disputes, as well as canceled order line items (transactions). However, this call does not retrieve Item Not Received and Significantly Not As Described disputes created by buyers through the eBay Resolution Center. The Resolution Center is part of the eBay Buyer Protection program. As a seller, it is a good practice to call getUserCases of the Resolutions API in order to capture all cases/disputes in which you are involved. If you do call getUserCases, look at the caseId.type value in each caseSummary node. If the case type is EBP_INR or EBP_SNAD, you must subsequently call getEBPCaseDetail of the Resolutions API to retrieve details on a specific case. For all other case types, you must subsequently call GetDispute to retrieve details on a specific dispute, or GetUserDisputes to retrieve details on multiple disputes.

GetDispute returns the following type of dispute information:

• Seller and buyer IDs
• The dispute explanation, state, status, and type
• Any messages in the dispute thread
• Whether the seller is currently eligible for a Final Value Fee credit
• Resolution types or reasons if the dispute has been resolved

For broader concepts and instructions, see Unpaid Item Disputes and Item Not Received Disputes.

Request Details

If you know the DisputeID of a specific dispute, you can use GetDispute to retrieve the information for that dispute. You must call GetDispute on the same site on which the dispute was opened.

The call returns a Dispute container which contains various information on that specific dispute, including values for DisputeCreditEligibility, DisputeExplanation, DisputeReason, DisputeRecordType, DisputeState, and DisputeStatus. It also returns the SellerUserId and BuyerUserId, as well as the time the dispute was created and last modified. Response details include the following:

• Each message added to the dispute appears in a DisputeMessage container that provides the MessageSource and MessageText. In addition to the BuyerUserID and SellerUserID values, MessageSource can have a value of eBay, since an eBay can add messages relating to the dispute administration.
• The Item container supplies information about the disputed item. It includes an ItemID, a Site element describing the site where the item was listed, the Title under which the item was listed, the Quantity of items purchased, the price of the item (CurrentPrice), and the CurrencyID that applied at the time the buyer committed to purchasing the item.
• A value for DisputeRecordType, which specifies the type of dispute as either UnpaidItem or ItemNotReceived.
• When the dispute is resolved, the response contains one or more DisputeResolution elements.
• The DisputeState value in the response is useful when you want to call AddDisputeResponse.
• The DisputeCreditEligibility element shows whether or not the dispute is currently eligible for credit (note that this element does not state whether a credit will ultimately will be issued to the seller).

In most cases, the seller must wait 7 days for the buyer to respond after opening the dispute; thus, the value of DisputeCreditEligibility is InEligible during that time. There are exceptions to this rule. For example, if the buyer is not a registered user or if the buyer requested shipment to a country that the seller does not ship to. In these cases, the value may be Eligible immediately after the dispute was opened.

If you have an ItemID value and you need to retrieve a TransactionID, you can call GetItemTransactions or GetSellerTransactions. When you obtain the TransactionID, store it in your application so you do not have to make repeated calls to GetDispute.

Testing GetDispute

You can test GetDispute in the Sandbox. To test this call:

1. Set up at least one buyer and one seller in the Sandbox environment.
2. Create an order line item (have the seller list an item and the buyer confirm a purchase, but not make an actual payment).
3. Call GetItemTransactions with the ItemID to get a TransactionID.
4. Let the order line item age at least 7 days. (Alternately, you can open a Support Ticket and, for a fee, eBay will artificially age your listing for you.)
5. Create a dispute with AddDispute.
6. Call GetDispute on the dispute to see if you can get a dispute record.
7. Add several comments to the dispute with AddDisputeResponse.
8. Call GetDispute on the dispute again. Check if you can see the comments added to the dispute.
9. Close the dispute with AddDisputeResponse. Call GetDispute again to retrieve the dispute. Check that the dispute state is closed.

Related Information

See:
    Unpaid Item Disputes
    Buyer Disputes
    Getting Details About a Dispute

See also the reference documentation for these calls:

• AddDispute - Creates an Unpaid Item dispute against a buyer or cancels a single line item order.
• AddDisputeResponse - Adds a response or comment to a dispute, or closes a dispute.
• GetItemTransactions - Retrieves order line item (transaction) information for a specified ItemID.
• GetSellerTransactions - Retrieves order line item (transaction) information for the user for which the call is made, and not for any other user. Also for Half.com. (To retrieve order line items for another seller's listings, use GetItemTransactions.)
• GetUserDisputes - Requests a list of disputes the requester is involved in as buyer or seller. eBay Buyer Protection Item Not Received and Significantly Not As Described cases are not returned with this call.
• SellerReverseDispute - Enables a seller to "reverse" an Unpaid Item dispute that has been closed, for example, if buyer and seller reach an agreement. The seller's Final Value Fee credit and the buyer's strike are both reversed. if applicable.

Back to top

GetDispute Input

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

The XML prototype does not include requester credentials. This is a documentation limitation only (see Standard Requester Credentials for Making Calls).

<?xml version="1.0" encoding="utf-8"?>
<GetDisputeRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <DisputeID> DisputeIDType (string) </DisputeID>
  <!-- Standard Input Fields -->
  <ErrorLanguage> string </ErrorLanguage>
  <MessageID> string </MessageID>
  <Version> string </Version>
  <WarningLevel> WarningLevelCodeType </WarningLevel>
</GetDisputeRequest>

Back to top

GetDispute Output

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).

<?xml version="1.0" encoding="utf-8"?>
<GetDisputeResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Output Fields -->
  <Dispute> DisputeType
    <BuyerUserID> UserIDType (string) </BuyerUserID>
    <DisputeCreatedTime> dateTime </DisputeCreatedTime>
    <DisputeCreditEligibility> DisputeCreditEligibilityCodeType </DisputeCreditEligibility>
    <DisputeExplanation> DisputeExplanationCodeType </DisputeExplanation>
    <DisputeID> DisputeIDType (string) </DisputeID>
    <DisputeMessage> DisputeMessageType
      <MessageCreationTime> dateTime </MessageCreationTime>
      <MessageID> int </MessageID>
      <MessageSource> DisputeMessageSourceCodeType </MessageSource>
      <MessageText> string </MessageText>
    </DisputeMessage>
    <!-- ... more DisputeMessage nodes allowed here ... -->
    <DisputeModifiedTime> dateTime </DisputeModifiedTime>
    <DisputeReason> DisputeReasonCodeType </DisputeReason>
    <DisputeRecordType> DisputeRecordTypeCodeType </DisputeRecordType>
    <DisputeState> DisputeStateCodeType </DisputeState>
    <DisputeStatus> DisputeStatusCodeType </DisputeStatus>
    <Escalation> boolean </Escalation>
    <Item> ItemType
      <ItemID> ItemIDType (string) </ItemID>
      <ListingDetails> ListingDetailsType
        <EndTime> dateTime </EndTime>
        <StartTime> dateTime </StartTime>
      </ListingDetails>
      <Quantity> int </Quantity>
      <SellingStatus> SellingStatusType
        <ConvertedCurrentPrice> AmountType (double) </ConvertedCurrentPrice>
        <CurrentPrice> AmountType (double) </CurrentPrice>
      </SellingStatus>
      <Site> SiteCodeType </Site>
      <Title> string </Title>
    </Item>
    <OrderLineItemID> string </OrderLineItemID>
    <PurchaseProtection> boolean </PurchaseProtection>
    <SellerUserID> UserIDType (string) </SellerUserID>
    <TransactionID> string </TransactionID>
  </Dispute>
  <!-- Standard Output Fields -->
  <Ack> AckCodeType </Ack>
  <Build> string </Build>
  <CorrelationID> string </CorrelationID>
  <Errors> ErrorType
    <ErrorClassification> ErrorClassificationCodeType </ErrorClassification>
    <ErrorCode> token </ErrorCode>
    <ErrorParameters ParamID="string"> ErrorParameterType
      <Value> string </Value>
    </ErrorParameters>
    <!-- ... more ErrorParameters nodes allowed here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes allowed here ... -->
  <HardExpirationWarning> string </HardExpirationWarning>
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
</GetDisputeResponse>

Back to top

GetDispute Detail Controls

Detail Control: DetailLevel

This call does not support varying Detail Levels. You do not need to pass DetailLevel in the request.

Back to top

GetDispute Samples

New to making API calls? Please see Routing the Request.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Retrieves data for an Unpaid Item dispute.

Description

The requester is the seller involved in this dispute, and he is looking for information on the unpaid item.

Input

For input, the seller provides the DisputeID for the dispute.

XML format (HTTP POST). Also available is the .txt version of this XML.

<?xml version="1.0" encoding="utf-8"?>
<GetDisputeRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken>ABC...123</eBayAuthToken>
  </RequesterCredentials>
  <DisputeID>213833</DisputeID>
</GetDisputeRequest>

Output

The response describes the Unpaid Item dispute. Note that the value of DisputeRecordType is UnpaidItem.

XML format. Also available is the .txt version of this XML.

<?xml version="1.0" encoding="utf-8"?>
<GetDisputeResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2005-03-11T01:59:20.393Z</Timestamp>
  <Ack>Success</Ack>
  <CorrelationID>
    00000000-00000000-00000000-00000000-00000000-00000000-0000000000
  </CorrelationID>
  <Version>401</Version>
  <Build>20050308050919</Build>
  <Dispute>
    <DisputeID>213833</DisputeID>
    <DisputeRecordType>UnpaidItem</DisputeRecordType>
    <DisputeState>BuyerFirstResponsePayOption</DisputeState>
    <DisputeStatus>WaitingForBuyerResponse</DisputeStatus>
    <BuyerUserID>samplebuyer</BuyerUserID>
    <SellerUserID>sampleseller</SellerUserID>
    <TransactionID>748970</TransactionID>
    <Item> 
      <ItemID>9202501086</ItemID>
      <ListingDetails>
        <StartTime>2005-02-08T02:37:07.000Z</StartTime>
        <EndTime>2005-02-08T02:39:43.000Z</EndTime>
      </ListingDetails>
      <Quantity>1</Quantity>
      <SellingStatus>
        <ConvertedCurrentPrice currencyID="USD">199.0</ConvertedCurrentPrice>
        <CurrentPrice currencyID="USD">199.0</CurrentPrice>
      </SellingStatus>
      <Site>US</Site>
      <Title>Antique Silver Candelabra</Title>
    </Item>
    <DisputeReason>BuyerHasNotPaid</DisputeReason>
    <DisputeExplanation>BuyerHasNotResponded</DisputeExplanation>
    <DisputeCreditEligibility>InEligible</DisputeCreditEligibility>
    <DisputeCreatedTime>2005-03-10T02:50:37.000Z</DisputeCreatedTime>
    <DisputeModifiedTime>2005-03-10T18:11:46.000Z</DisputeModifiedTime>
    <DisputeMessage>
      <MessageID>428660</MessageID>
      <MessageSource>eBay</MessageSource>
      <MessageCreationTime>2005-03-10T02:50:40.000Z</MessageCreationTime>
      <MessageText>
        An Unpaid Item dispute has been opened for the following item:
        Antique Silver Candelabra (#9202501086)
        Reason given for Unpaid Item: The buyer has not paid for the item.
        Buyer actions reported by seller: The buyer has not responded.
      </MessageText>
    </DisputeMessage>
    <DisputeMessage>
      <MessageID>428699</MessageID>
      <MessageSource>Seller</MessageSource>
      <MessageCreationTime>2005-03-10T18:11:02.000Z</MessageCreationTime>
      <MessageText>No response from the buyer in 10 days</MessageText>
    </DisputeMessage>
    <DisputeMessage> 
      <MessageID>428700</MessageID>
      <MessageSource>Seller</MessageSource>
      <MessageCreationTime>2005-03-10T18:11:29.000Z</MessageCreationTime>
      <MessageText>Still attempting to contact the buyer</MessageText>
    </DisputeMessage>
    <DisputeMessage>
      <MessageID>428701</MessageID>
      <MessageSource>Seller</MessageSource>
      <MessageCreationTime>2005-03-10T18:11:46.000Z</MessageCreationTime>
      <MessageText>Last attempt to contact the buyer</MessageText>
    </DisputeMessage>
    <Escalation>false</Escalation>
    <PurchaseProtection>false</PurchaseProtection>
  </Dispute>
</GetDisputeResponse>

Back to top

GetDispute Change History

Back to top

User-Contributed Notes

Copyright © 2005–2013 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.