openapi: 3.0.3
info:
  title: Paypal Subscriptions Authorizations Disputes-Actions API
  description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
  version: '1.6'
  contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
  description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
  description: PayPal Live Environment
tags:
- 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>
paths:
  /v1/customer/disputes/{id}/provide-evidence:
    post:
      summary: Paypal Provide evidence
      description: Provides evidence for a dispute, by ID. A merchant can provide evidence for disputes with the <code>WAITING_FOR_SELLER_RESPONSE</code> status while customers can provide evidence for disputes with the <code>WAITING_FOR_BUYER_RESPONSE</code> status. Evidence can be a proof of delivery or proof of refund document or notes, which can include logs. A proof of delivery document includes a tracking number while a proof of refund document includes a refund ID. For other evidence type, notes and documents can be given. Evidences requested from you can be found by checking the type of evidence for the corresponding source under the evidence section of the <a href="/docs/api/customer-disputes/v1/#disputes_get">show dispute details</a> response. The source will be <code>REQUESTED_FROM_SELLER</code> for evidences requested from the merchant while it will be <code>REQUESTED_FROM_BUYER</code> for evidences requested from the customer. For constraints and rules regarding documents, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#documents">documents</a>.<br/>To make this request, specify the evidence in the JSON request body and use the <code>provide-evidence</code> link in the <a href="/docs/api/reference/api-responses/#hateoas-links/">HATEOAS links</a> of the <a href="/docs/api/customer-disputes/v1/#disputes_get">show dispute details</a> response. In case the link is not present in the response, you can't provide evidence for the dispute. For information about dispute reasons, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#dispute-reasons">dispute reasons</a>.
      operationId: disputes.provide-evidence
      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'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        $ref: '#/components/requestBodies/evidences'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-seller
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-buyer
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-partner
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/appeal:
    post:
      summary: Paypal Appeal dispute
      description: Appeals a dispute, by ID. To appeal a dispute, use the <code>appeal</code> link in the <a href="/docs/api/reference/api-responses/#hateoas-links/">HATEOAS links</a> from the show dispute details response. If this link does not appear, you cannot appeal the dispute. Submit new evidence as a document or notes in the JSON request body. For constraints and rules regarding documents, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#documents">documents</a>.<br/>To make this request, specify the dispute ID in the URI and specify the evidence in the JSON request body. For information about dispute reasons, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#dispute-reasons">dispute reasons</a>.
      operationId: disputes.appeal
      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'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        $ref: '#/components/requestBodies/evidences'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-seller
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-buyer
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/accept-claim:
    post:
      summary: Paypal Accept claim
      description: Accepts liability for a claim, by ID. When you accept liability for a claim, the dispute closes in the customer’s favor and PayPal automatically refunds money to the customer from the merchant's account. Allowed accept_claim_type values for the request is available in dispute details <a href="/docs/api/customer-disputes/v1/#definition-allowed_response_options">allowed response options</a> object.
      operationId: disputes.accept-claim
      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'
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                accept-claim-document:
                  description: A file with evidence.
                  type: string
                  format: binary
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-seller
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/adjudicate:
    post:
      summary: Paypal Settle dispute
      description: <blockquote><strong>Important:</strong> This method is for sandbox use only.</blockquote> Settles a dispute in either the customer's or merchant's favor. Merchants can make this call in the sandbox to complete end-to-end dispute resolution testing, which mimics the dispute resolution that PayPal agents normally complete. To make this call, the dispute <code>status</code> must be <code>UNDER_REVIEW</code> and <code>adjudicate</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.
      operationId: disputes.adjudicate
      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'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/adjudicate'
            examples:
              adjudicate:
                value:
                  adjudication_outcome: BUYER_FAVOR
          multipart/related:
            schema:
              $ref: '#/components/schemas/adjudicate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/adjudicate'
          multipart/mixed:
            schema:
              $ref: '#/components/schemas/adjudicate'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-seller
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-buyer
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/require-evidence:
    post:
      summary: Paypal 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
      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'
      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
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-seller
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-buyer
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/escalate:
    post:
      summary: Paypal Escalate dispute to claim
      description: Escalates the dispute, by ID, to a PayPal claim. To make this call, the stage in the dispute lifecycle must be `INQUIRY`.
      operationId: disputes.escalate
      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'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/escalate'
            examples:
              require_evidence:
                value:
                  action: BUYER_EVIDENCE
          multipart/related:
            schema:
              $ref: '#/components/schemas/escalate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/escalate'
          multipart/mixed:
            schema:
              $ref: '#/components/schemas/escalate'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-seller
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-buyer
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/send-message:
    post:
      summary: Paypal Send message about dispute to other party
      description: Sends a message about a dispute, by ID, to the other party in the dispute. Merchants and customers can only send messages if the `dispute_life_cycle_stage` value is `INQUIRY`. For constraints and rules regarding documents that can be attached as part of the message, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#documents">documents</a>. To send a message, use the <code>send-message</code> link in the <a href="/docs/api/reference/api-responses/#hateoas-links/">HATEOAS links</a> of the <a href="/docs/api/customer-disputes/v1/#disputes_get">show dispute details</a> response and specify the message in the JSON request body. In case the link is not present in the response you can't send a message on the dispute.
      operationId: disputes.send-message
      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'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                message_document:
                  description: A file that contains any additional info about the message posted.
                  type: string
                  format: binary
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-seller
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-buyer
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/make-offer:
    post:
      summary: Paypal Make offer to resolve dispute
      description: Makes an offer to the other party to resolve a dispute, by ID. To make this call, the stage in the dispute lifecycle must be `INQUIRY`. If the customer accepts the offer, PayPal automatically makes a refund. Allowed offer_type values for the request is available in dispute details <a href="/docs/api/customer-disputes/v1/#definition-allowed_response_options">allowed response options</a> object.
      operationId: disputes.make-offer
      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'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/make_offer'
            examples:
              make_offer:
                value:
                  note: Offer refund with replacement item.
                  offer_amount:
                    currency_code: USD
                    value: '23'
                  offer_type: REFUND_WITH_REPLACEMENT
          multipart/related:
            schema:
              $ref: '#/components/schemas/make_offer'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/make_offer'
          multipart/mixed:
            schema:
              $ref: '#/components/schemas/make_offer'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-seller
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-buyer
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/accept-offer:
    post:
      summary: Paypal Accept offer to resolve dispute
      description: The customer accepts the offer from merchant to resolve a dispute, by ID. PayPal automatically refunds the amount proposed by merchant to the customer.
      operationId: disputes.accept-offer
      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'
        '202':
          description: A successfully accepted request returns the HTTP `202 Accepted` status code and a JSON response body that includes a [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) to the ID of the request. The request returns `202 Accepted` status in case money movement for the offer is delayed due to some internal reasons.
          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'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/accept_offer'
            examples:
              accept_offer:
                value:
                  note: I am ok with the refund offered.
          multipart/related:
            schema:
              $ref: '#/components/schemas/accept_offer'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/accept_offer'
          multipart/mixed:
            schema:
              $ref: '#/components/schemas/accept_offer'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-buyer
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/deny-offer:
    post:
      summary: Paypal Deny offer to resolve dispute
      description: Denies an offer that the merchant proposes for a dispute, by ID.
      operationId: disputes.deny-offer
      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'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deny_offer'
            examples:
              deny_offer:
                value:
                  note: refund offer is very low.
          multipart/related:
            schema:
              $ref: '#/components/schemas/deny_offer'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/deny_offer'
          multipart/mixed:
            schema:
              $ref: '#/components/schemas/deny_offer'
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-buyer
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/acknowledge-return-item:
    post:
      summary: Paypal Acknowledge returned item
      description: Acknowledges that the customer returned an item for a dispute, by ID. A merchant can make this request for disputes with the `MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED` reason. Allowed acknowledgement_type values for the request is available in dispute details <a href="/docs/api/customer-disputes/v1/#definition-allowed_response_options">allowed response options</a> object. For constraints and rules regarding documents, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#documents">documents</a>.
      operationId: disputes.acknowledge-return-item
      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'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                acknowledgement_document:
                  description: A file with evidence.
                  type: string
                  format: binary
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-seller
      tags:
      - Disputes-Actions
  /v1/customer/disputes/{id}/provide-supporting-info:
    post:
      summary: Paypal Provide supporting information for dispute
      description: Provides supporting information for a dispute, by ID. A merchant or buyer can make this request for disputes if they find the `provide-supporting-info` link in the HATEOAS links in the list disputes response. The party can provide the supporting information to PayPal to defend themselves only when the `dispute_life_cycle_stage` is `CHARGEBACK`, `PRE_ARBITRATION`, or `ARBITRATION`. They can provide a note that describes their part with details or upload any supporting documents to support their side. For constraints and rules regarding documents, see <a href="/docs/integration/direct/customer-disputes/integration-guide/#documents">documents</a>.<br/>To make this request, specify the dispute ID in the URI and specify the notes in the JSON request body. This method differs from the provide evidence method which supports only multipart request, where PayPal asks the concerned party for evidence.
      operationId: disputes.provide-supporting-info
      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'
        '404':
          description: The request failed due to the dispute is not available. The request returns the HTTP `404 Not Found` 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'
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                supporting document:
                  description: A file with evidence.
                  type: string
                  format: binary
      security:
      - Oauth2:
        - https://uri.paypal.com/services/disputes/update-seller
        - https://uri.paypal.com/services/disputes/update-buyer
        - https://uri.paypal.com/services/disputes/update-partner
      tags:
      - Disputes-Actions
components:
  schemas:
    offer_type:
      type: string
      minLength: 1
      maxLength: 255
      pattern: ^[0-9A-Z_]+$
      title: Offer Type
      description: The merchant-proposed offer type for the dispute.
      enum:
      - REFUND
      - REFUND_WITH_RETURN
      - REFUND_WITH_REPLACEMENT
      - REPLACEMENT_WITHOUT_REFUND
    accept_offer:
      type: object
      title: Accept Offer Request
      description: A customer request to accept the offer made by the merchant.
      properties:
        note:
          type: string
          minLength: 1
          maxLength: 2000
          description: The customer notes about accepting of offer. PayPal can but the merchant cannot view these notes.
    buyer_escalation_reason: {}
    escalate:
      type: object
      title: Escalate Claim Request
      description: A merchant request to escalate a dispute, by ID, to a PayPal claim.
      properties:
        note:
          type: string
          minLength: 1
          maxLength: 2000
          description: The notes about the escalation of the dispute to a claim.
        buyer_escalation_reason:
          $ref: '#/components/schemas/buyer_escalation_reason'
      required:
      - note
    address_portable:
      type: object
      title: Portable Postal Address (Medium-Grained)
      description: 'The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).'
      properties:
        address_line_1:
          type: string
          description: The first line of the address. For example, number or street. For example, `173 Drury Lane`. Required for data entry and compliance and risk checks. Must contain the full address.
          maxLength: 300
        address_line_2:
          type: string
          description: The second line of the address. For example, suite or apartment number.
          maxLength: 300
        address_line_3:
          type: string
          description: The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as `next to Walmart`, or a landmark in an Indian address.
          maxLength: 100
        admin_area_4:
          type: string
          description: The neighborhood, ward, or district. Smaller than `admin_area_level_3` or `sub_locality`. Value is:<ul><li>The postal sorting code for Guernsey and many French territories, such as French Guiana.</li><li>The fine-grained administrative levels in China.</li></ul>
          maxLength: 100
        admin_area_3:
          type: string
          description: A sub-locality, suburb, neighborhood, or district. Smaller than `admin_area_level_2`. Value is:<ul><li>Brazil. Suburb, bairro, or neighborhood.</li><li>India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.</li></ul>
          maxLength: 100
        admin_area_2:
          type: string
          description: A city, town, or village. Smaller than `admin_area_level_1`.
          maxLength: 120
        admin_area_1:
          type: string
          description: The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, `CA` and not `California`. Value, by country, is:<ul><li>UK. A county.</li><li>US. A state.</li><li>Canada. A province.</li><li>Japan. A prefecture.</li><li>Switzerland. A kanton.</li></ul>
          maxLength: 300
        postal_code:
          type: string
          description: The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code).
          maxLength: 60
        country_code:
          $ref: '#/components/schemas/country_code'
        address_details:
          type: object
          title: Address Details
          description: The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.<br/>For example, `address_portable.address_line_1` is usually a combination of `address_details.street_number`, `street_name`, and `street_type`.
          properties:
            street_number:
              type: string
              description: The street number.
              maxLength: 100
            street_name:
              type: string
              description: The street name. Just `Drury` in `Drury Lane`.
              maxLength: 100
            street_type:
              type: string
              description: The street type. For example, avenue, boulevard, road, or expressway.
              maxLength: 100
            delivery_service:
              type: string
              description: The delivery service. Post office box, bag number, or post office name.
              maxLength: 100
            building_name:
              type: string
              description: A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, <code>Craven House</code>.
              maxLength: 100
            sub_building:
              type: string
              description: The first-order entity below a named building or location that represents the sub-premises. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
              maxLength: 100
      required:
      - country_code
    country_code:
      type: string
      description: The [two-character ISO 3166-1 code](/docs/api/reference/country-codes/) that identifies the country or region.<blockquote><strong>Note:</strong> The country code for Great Britain is <code>GB</code> and not <code>UK</code> as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.</blockquote>
      format: ppaas_common_country_code_v2
      maxLength: 2
      minLength: 2
      pattern: ^([A-Z]{2}|C2)$
    adjudicate:
      type: object
      title: Settle Request
      description: A request to settle a dispute in either the customer's or merchant's favor.
      properties:
        adjudication_outcome:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[0-9A-Z_]+$
          description: The outcome of the adjudication.
          enum:
          - BUYER_FAVOR
          - SELLER_FAVOR
      required:
      - adjudication_outcome
    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:
          type: array
          description: An array of additional details about the error.
          items:
            $ref: '#/components/schemas/error_details-2'
        links:
          type: array
          description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
          readOnly: true
          items:
            $ref: '#/components/schemas/link_description'
            readOnly: true
      required:
      - name
      - message
      - debug_id
    make_offer:
      type: object
      title: Make Offer Request
      description: A merchant request to make an offer to resolve a dispute.
      properties:
        note:
          type: string
          minLength: 1
          maxLength: 2000
          description: The merchant's notes about the offer.
        offer_amount:
          description: The amount proposed to resolve the dispute.
          $ref: '#/components/schemas/money'
        return_shipping_address:
          description: The return address for the item. Required when the customer must return an item to the merchant for the <code>MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED</code> dispute reason, especially if the refund amount is less than the dispute amount.
          $ref: '#/components/schemas/address_portable'
        invoice_id:
          type: string
          minLength: 1
          maxLength: 127
          description: The merchant-provided ID of the invoice for the refund. This optional value maps the refund to an invoice ID in the merchant's system.
          pattern: ^[A-Za-z0-9:\-|]+$
        offer_type:
          $ref: '#/components/schemas/offer_type'
      required:
      - note
      - offer_type
    subsequent_action:
      title: Subsequent Action
      type: object
      description: The subsequent action.
      properties:
        links:
          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'
            readOnly: true
    link_description:
      type: object
      title: Link Description
      description: The request-related [HATEOAS link](/docs/api/reference/api-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
    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.
          enum:
          - BUYER_EVIDENCE
          - SELLER_EVIDENCE
      required:
      - action
    currency_code:
      description: The [three-character ISO-4217 currency code](/docs/api/reference/currency-codes/) that identifies the currency.
      type: string
      format: ppaas_common_currency_code_v2
      minLength: 3
      maxLength: 3
    deny_offer:
      type: object
      title: Deny Offer Request
      description: A customer request to deny the offer made by the merchant.
      properties:
        note:
          type: string
          minLength: 1
          maxLength: 2000
          description: The customer notes about the denial of offer. PayPal can but the merchant cannot view these notes.
      required:
      - note
    money:
      type: object
      title: Money
      description: The currency and amount for a financial transaction, such as a balance or payment due.
      properties:
        currency_code:
          $ref: '#/components/schemas/currency_code'
        value:
          type: string
          description: The value, which might be:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see [Currency Codes](/docs/api/reference/currency-codes/).
          maxLength: 32
          pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
      required:
      - currency_code
      - value
    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
  requestBodies:
    evidences:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              evidence-file:
                description: A file with evidence.
                type: string
                format: binary
  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-]+$
  securitySchemes:
    Oauth2:
      type: oauth2
      description: Oauth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: /v1/oauth2/token
          scopes:
            https://uri.paypal.com/services/subscriptions: Manage plan & subscription
externalDocs:
  url: https://developer.paypal.com/docs/api/subscriptions/v1/