> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update dispute status

> <blockquote><strong>Important:</strong> This method is for sandbox use only.</blockquote> Updates the status of a dispute, by ID, from <code>UNDER_REVIEW</code> to either:<ul><li><code>WAITING_FOR_BUYER_RESPONSE</code></li><li><code>WAITING_FOR_SELLER_RESPONSE</code></li></ul>This status change enables either the customer or merchant to submit evidence for the dispute. To make this call, the dispute <code>status</code> must be <code>UNDER_REVIEW</code> and <code>require-evidence</code> link  should be available in the <a href="/docs/api/customer-disputes/v1/#disputes_get!c=200&path=links&t=response/">HATEOAS links</a> of the <a href="/docs/api/customer-disputes/v1/#disputes_get">show dispute details</a> response. Specify an <code>action</code> value in the JSON request body to indicate whether the status change enables the customer or merchant to submit evidence:<table><thead><tr align="left"><th>If <code>action</code> is</th><th>The <code>status</code> updates to</th></tr></thead><tbody><tr><td><code>BUYER_EVIDENCE</code></td><td> <code>WAITING_FOR_BUYER_RESPONSE</code></td></tr><tr><td><code>SELLER_EVIDENCE</code></td><td> <code>WAITING_FOR_SELLER_RESPONSE</code></td></tr></tbody></table>.



## OpenAPI

````yaml /api-reference/customer_disputes_v1.json post /v1/customer/disputes/{id}/require-evidence
openapi: 3.0.3
info:
  title: Disputes
  description: >-
    Occasionally, something goes wrong with a customer's order. To dispute a
    charge, a customer can create a dispute with PayPal. PayPal merchants,
    partners, and external developers can use the PayPal Disputes API to manage
    customer disputes.<blockquote><strong>Note:</strong> In the live
    environment, merchants cannot create disputes but can only respond to
    customer-created disputes. However, merchants can create disputes in the
    sandbox environment. When you create an app, enable Disputes in the App
    feature options section.</blockquote>A customer can also ask his or her bank
    or credit card company to dispute and reverse a charge, which is known as a
    <i>chargeback</i>. For more information, see <a
    href="https://www.paypal.com/us/brc/article/customer-disputes-claims-chargebacks-bank-reversals">Disputes,
    claims, chargebacks, and bank reversals</a>.<br/><br/>When a customer
    disputes a charge, you can use this API to provide evidence that the charge
    is legitimate. To provide evidence or appeal a dispute, you submit a proof
    of delivery or proof of refund document or notes, which can include
    logs.<br/><br/>Normally, an agent at PayPal creates a dispute, updates the
    dispute status, and settles disputes, but now you can run test cases in the
    sandbox that complete these
    operations.<br/><br/><blockquote><strong>Important:</strong> The create,
    cancel, compute metrics, change reason, and validate eligibility methods are
    available as a limited-release solution at this time. For more information,
    reach out to your PayPal account manager.</blockquote><br/>For details, see
    <a href="/docs/integration/direct/customer-disputes/">Disputes Overview</a>
    documentation.
  version: '1.11'
  contact: {}
servers:
  - url: https://api-m.sandbox.paypal.com
    description: PayPal Sandbox Environment
  - url: https://api-m.paypal.com
    description: PayPal Live Environment
security: []
tags:
  - name: disputes
    description: >-
      Use the `/disputes` resource to list disputes, create disputes, show
      dispute details, and partially a dispute. Normally, an agent at PayPal
      creates disputes but now you can run test cases in the sandbox that create
      disputes.
  - name: disputes-actions
    description: >-
      Use the `/disputes` resource with a dispute ID and an action
      to:<ul><li>Accept a claim.</li><li>Accept an offer to resolve a
      dispute.</li><li>Acknowledge the return of an item related to a
      dispute.</li><li>Settle a dispute.</li><li>Appeal a
      dispute.</li><li>Cancel a dispute.</li><li>Change the reason for a
      dispute.</li><li>Deny an offer to resolve dispute.</li><li>Escalate a
      dispute to a claim.</li><li>Make an offer to resolve a
      dispute.</li><li>Make an offer to resolve a dispute.</li><li>Provide
      evidence for a dispute.</li><li>Provide supporting information for
      dispute.</li><li>In the sandbox, update the dispute status.</li><li>Send a
      message about a dispute to the other party in the dispute.</li><ul>
  - name: referred-disputes
    description: >-
      Use the `/customer/referred-disputes` resource to create a dispute for a
      referred case that was created by a partner or marketplace, show details
      for a referred dispute, by ID, notify referred refunds completed to
      PayPal, notify PayPal about referred dispute adjudication updates, and
      determine the dispute eligibility for referred disputes.
  - name: validate-eligibility
    description: >-
      Use the `/validate-eligibility/` resource to determine whether you can
      create a case for a transaction.
  - name: compute-metrics
    description: Use the `/compute-metrics` resource to provide metrics for all disputes.
  - name: validate-referred-dispute-eligibility
    description: >-
      Use the `/validate-referred-dispute-eligibility` resource to determine
      whether you can create a referred case for a transaction, by encrypted
      transaction ID.
  - name: referred-disputes
    description: >-
      Use the `/referred-disputes` resource to create a dispute for a referred
      case that was created by a partner or marketplace, show details for a
      referred dispute, by ID, notify referred refunds completed to PayPal,
      notify PayPal about referred dispute adjudication updates, and determine
      the dispute eligibility for referred disputes.
  - name: referred-disputes-actions
    description: >-
      Use the `/referred-disputes` resource with a dispute ID and an action to
      notify PayPal about adjudication updates for a referred dispute and notify
      PayPal about a refund for a referred dispute.
  - name: partner-actions
    description: >-
      Use the `/disputes/{id}/partner-actions/` resource to show dispute action
      details and partially update a dispute action.
  - name: search-suggestions
    description: Use the `/search-suggestions` resource to show search suggestions.
  - name: dispute-events
    description: Use the `/dispute-events` resource to send dispute events.
  - name: refund-preference
    description: >-
      Use the `/disputes/{id}/provide-refund-preference` resource to provide
      refund preferences for the dispute.
  - name: return-compensation
    description: >-
      Use the `/disputes/{id}/return-compensation` resource to return the
      compensation on the dispute provided by PayPal to the customer.
externalDocs:
  url: https://developer.paypal.com/docs/api/customer-disputes/v1/
paths:
  /v1/customer/disputes/{id}/require-evidence:
    post:
      tags:
        - disputes-actions
      summary: Update dispute status
      description: >-
        <blockquote><strong>Important:</strong> This method is for sandbox use
        only.</blockquote> Updates the status of a dispute, by ID, from
        <code>UNDER_REVIEW</code> to
        either:<ul><li><code>WAITING_FOR_BUYER_RESPONSE</code></li><li><code>WAITING_FOR_SELLER_RESPONSE</code></li></ul>This
        status change enables either the customer or merchant to submit evidence
        for the dispute. To make this call, the dispute <code>status</code> must
        be <code>UNDER_REVIEW</code> and <code>require-evidence</code> link 
        should be available in the <a
        href="/docs/api/customer-disputes/v1/#disputes_get!c=200&path=links&t=response/">HATEOAS
        links</a> of the <a
        href="/docs/api/customer-disputes/v1/#disputes_get">show dispute
        details</a> response. Specify an <code>action</code> value in the JSON
        request body to indicate whether the status change enables the customer
        or merchant to submit evidence:<table><thead><tr align="left"><th>If
        <code>action</code> is</th><th>The <code>status</code> updates
        to</th></tr></thead><tbody><tr><td><code>BUYER_EVIDENCE</code></td><td>
        <code>WAITING_FOR_BUYER_RESPONSE</code></td></tr><tr><td><code>SELLER_EVIDENCE</code></td><td>
        <code>WAITING_FOR_SELLER_RESPONSE</code></td></tr></tbody></table>.
      operationId: disputes.require-evidence
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/require_evidence'
            examples:
              escalate:
                value:
                  note: Escalating to PayPal claim for resolution.
          multipart/related:
            schema:
              $ref: '#/components/schemas/require_evidence'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/require_evidence'
          multipart/mixed:
            schema:
              $ref: '#/components/schemas/require_evidence'
        required: true
      responses:
        '200':
          description: >-
            A successful request returns the HTTP `200 OK` status code and a
            JSON response body that includes a link to the dispute.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subsequent_action'
        '400':
          description: >-
            The request failed due to a validation error. The request returns
            the HTTP `400 Bad Request` status code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: >-
            The requested action could not be completed. The request returns the
            HTTP `422 Unprocessable Entity` status code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: >-
            An internal server error occurred. The request returns the HTTP `500
            Internal Server Error` status code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
        - Oauth2:
            - https://uri.paypal.com/services/disputes/update-seller
        - Oauth2:
            - https://uri.paypal.com/services/disputes/update-buyer
components:
  parameters:
    id:
      name: id
      in: path
      description: The ID of the dispute for which to provide the supporting information.
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[A-Za-z0-9-]+$
  schemas:
    require_evidence:
      type: object
      title: Require Evidence Request
      description: >-
        Sandbox only. Updates the state of a dispute, by ID, to either
        <code>WAITING_FOR_BUYER_RESPONSE</code> or
        <code>WAITING_FOR_SELLER_RESPONSE</code>. This state change enables
        either the customer or merchant to submit evidence for the dispute.
        Specify an <code>action</code> value in the JSON request body to
        indicate whether the state change enables the customer or merchant to
        submit evidence.
      properties:
        action:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[0-9A-Z_]+$
          description: >-
            The action. Indicates whether the state change enables the customer
            or merchant to submit evidence.
          x-enumDescriptions:
            - value: BUYER_EVIDENCE
              description: >-
                Changes the status of the dispute to
                <code>WAITING_FOR_BUYER_RESPONSE</code>.
            - value: SELLER_EVIDENCE
              description: >-
                Changes the status of the dispute to
                <code>WAITING_FOR_SELLER_RESPONSE</code>.
          enum:
            - BUYER_EVIDENCE
            - SELLER_EVIDENCE
      required:
        - action
    subsequent_action:
      title: Subsequent Action
      type: object
      description: The subsequent action.
      properties:
        links:
          $ref: '#/components/schemas/definitions-link_description_list'
    error:
      type: object
      title: Error
      description: The error details.
      properties:
        name:
          type: string
          description: The human-readable, unique name of the error.
        message:
          type: string
          description: The message that describes the error.
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        information_link:
          type: string
          description: >-
            The information link, or URI, that shows detailed information about
            this error for the developer.
          readOnly: true
        details:
          $ref: '#/components/schemas/error_details_list'
        links:
          $ref: '#/components/schemas/link_description_list'
      required:
        - name
        - message
        - debug_id
    definitions-link_description_list:
      type: array
      minItems: 1
      maxItems: 10
      description: >-
        An array of request-related [HATEOAS
        links](/docs/api/reference/api-responses/#hateoas-links/).
      readOnly: true
      items:
        $ref: '#/components/schemas/link_description'
    error_details_list:
      type: array
      description: An array of additional details about the error.
      items:
        $ref: '#/components/schemas/error_details-2'
    link_description_list:
      type: array
      description: >-
        An array of request-related [HATEOAS
        links](/api/rest/responses/#hateoas-links).
      readOnly: true
      items:
        $ref: '#/components/schemas/link_description'
    link_description:
      type: object
      title: Link Description
      description: >-
        The request-related [HATEOAS link](/api/rest/responses/#hateoas-links)
        information.
      required:
        - href
        - rel
      properties:
        href:
          type: string
          description: >-
            The complete target URL. To make the related call, combine the
            method with this [URI
            Template-formatted](https://tools.ietf.org/html/rfc6570) link. For
            pre-processing, include the `$`, `(`, and `)` characters. The `href`
            is the key HATEOAS component that links a completed call with a
            subsequent call.
        rel:
          type: string
          description: >-
            The [link relation
            type](https://tools.ietf.org/html/rfc5988#section-4), which serves
            as an ID for a link that unambiguously describes the semantics of
            the link. See [Link
            Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
        method:
          type: string
          description: The HTTP method required to make the related call.
          enum:
            - GET
            - POST
            - PUT
            - DELETE
            - HEAD
            - CONNECT
            - OPTIONS
            - PATCH
    error_details-2:
      title: Error Details
      type: object
      description: The error details. Required for client-side `4XX` errors.
      properties:
        field:
          type: string
          description: >-
            The field that caused the error. If this field is in the body, set
            this value to the field's JSON pointer value. Required for
            client-side errors.
        value:
          type: string
          description: The value of the field that caused the error.
        location:
          type: string
          description: >-
            The location of the field that caused the error. Value is `body`,
            `path`, or `query`.
          default: body
        issue:
          type: string
          description: The unique, fine-grained application-level error code.
        description:
          type: string
          description: >-
            The human-readable description for an issue. The description can
            change over the lifetime of an API, so clients must not depend on
            this value.
      required:
        - issue
  securitySchemes:
    Oauth2:
      type: oauth2
      description: Oauth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: /v1/oauth2/token
          scopes:
            https://uri.paypal.com/services/disputes/read-seller: >-
              This privilege allows client to read and search a disputes of a
              merchant but gets only a limited and allowed set of fields back .
            https://uri.paypal.com/services/disputes/read-buyer: >-
              This privilege allows client to read and search disputes but
              returns a limited and allowed set of fields back.
            https://uri.paypal.com/services/disputes/read-ebay: >-
              This privilege allows client to read and search a disputes of an
              user but gets only a limited and allowed set of fields back to
              ebay.
            https://uri.paypal.com/services/disputes/read: >-
              This privilege allows client to read and search a dispute of an
              user with all fields.
            https://uri.paypal.com/services/disputes/webhooks: This privilege allows webhook platform to read a dispute event
            https://uri.paypal.com/services/disputes/create: >-
              This privilege allows client to validate eligibility and create a
              dispute on his transaction(s).
            https://uri.paypal.com/services/disputes/update-seller: >-
              This privilege allows client to update a dispute (Merchant
              actions).
            https://uri.paypal.com/services/disputes/update-buyer: >-
              This privilege allows client to update a dispute (customer
              actions).
            https://uri.paypal.com/services/referred-disputes/readwrite: >-
              This privilege allows client to read and update a referred
              dispute.
            https://uri.paypal.com/services/disputes/read-partner: >-
              This privilege allows client to read and search disputes but
              returns a limited and allowed set of fields back.
            https://uri.paypal.com/services/disputes/update-partner: >-
              This privilege allows client to update a dispute (Partner
              actions).

````