{"files":{"SKILL.md":"---\nname: disputes\ndescription: \"Disputes API skill. Use when working with Disputes for customer. Covers 15 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# Disputes\nAPI version: 1.11\n\n## Auth\nOAuth2\n\n## Base URL\nhttps://api-m.sandbox.paypal.com\n\n## Setup\n1. Configure auth: OAuth2\n2. GET /v1/customer/disputes -- list disputes\n3. POST /v1/customer/disputes/{id}/provide-evidence -- create first provide-evidence\n\n## Endpoints\n15 endpoints across 1 group. See references/api-spec.lap for full details.\n\n### Customer\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /v1/customer/disputes | List disputes |\n| GET | /v1/customer/disputes/{id} | Show dispute details |\n| PATCH | /v1/customer/disputes/{id} | Partially update dispute |\n| POST | /v1/customer/disputes/{id}/provide-evidence | Provide evidence |\n| POST | /v1/customer/disputes/{id}/appeal | Appeal dispute |\n| POST | /v1/customer/disputes/{id}/accept-claim | Accept claim |\n| POST | /v1/customer/disputes/{id}/adjudicate | Settle dispute |\n| POST | /v1/customer/disputes/{id}/require-evidence | Update dispute status |\n| POST | /v1/customer/disputes/{id}/escalate | Escalate dispute to claim |\n| POST | /v1/customer/disputes/{id}/send-message | Send message about dispute to other party |\n| POST | /v1/customer/disputes/{id}/make-offer | Make offer to resolve dispute |\n| POST | /v1/customer/disputes/{id}/accept-offer | Accept offer to resolve dispute |\n| POST | /v1/customer/disputes/{id}/deny-offer | Deny offer to resolve dispute |\n| POST | /v1/customer/disputes/{id}/acknowledge-return-item | Acknowledge returned item |\n| POST | /v1/customer/disputes/{id}/provide-supporting-info | Provide supporting information for dispute |\n\n## Common Questions\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"List all disputes?\" -> GET /v1/customer/disputes\n- \"Get dispute details?\" -> GET /v1/customer/disputes/{id}\n- \"Partially update a dispute?\" -> PATCH /v1/customer/disputes/{id}\n- \"Create a provide-evidence?\" -> POST /v1/customer/disputes/{id}/provide-evidence\n- \"Create a appeal?\" -> POST /v1/customer/disputes/{id}/appeal\n- \"Create a accept-claim?\" -> POST /v1/customer/disputes/{id}/accept-claim\n- \"Create a adjudicate?\" -> POST /v1/customer/disputes/{id}/adjudicate\n- \"Create a require-evidence?\" -> POST /v1/customer/disputes/{id}/require-evidence\n- \"Create a escalate?\" -> POST /v1/customer/disputes/{id}/escalate\n- \"Create a send-message?\" -> POST /v1/customer/disputes/{id}/send-message\n- \"Create a make-offer?\" -> POST /v1/customer/disputes/{id}/make-offer\n- \"Create a accept-offer?\" -> POST /v1/customer/disputes/{id}/accept-offer\n- \"Create a deny-offer?\" -> POST /v1/customer/disputes/{id}/deny-offer\n- \"Create a acknowledge-return-item?\" -> POST /v1/customer/disputes/{id}/acknowledge-return-item\n- \"Create a provide-supporting-info?\" -> POST /v1/customer/disputes/{id}/provide-supporting-info\n- \"How to authenticate?\" -> See Auth section above\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Paginated endpoints accept limit/offset or cursor parameters\n- Create/update endpoints return the modified resource on success\n- Error responses include status codes and descriptions in the spec\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Disputes\n@base https://api-m.sandbox.paypal.com\n@version 1.11\n@auth OAuth2\n@endpoints 15\n@toc customer(15)\n\n@endpoint GET /v1/customer/disputes\n@desc List disputes\n@optional {start_time: str=Current date and time # Filters the disputes in the response by a creation date and time. The start time must be within the last 180 days. Value is in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *`yyyy`*-*`MM`*-*`dd`*`T`*`HH`*:*`mm`*:*`ss`*.*`SSS`*`Z`.You can specify either but not both the `start_time` and `disputed_transaction_id` query parameters., disputed_transaction_id: str # Filters the disputes in the response by a transaction, by ID.You can specify either but not both the `start_time` and `disputed_transaction_id` query parameter., page_size: int=10 # Limits the number of disputes in the response to this value., next_page_token: str=The first page of data # The token that describes the next page of results to fetch. The list disputes call returns this token in the HATEOAS links in the response., dispute_state: str # Filters the disputes in the response by a state. Separate multiple values with a comma (`,`). When you specify more than one dispute_state, the response lists disputes that belong to any of the specified dispute_state., update_time_before: str # The date and time when the dispute was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *`yyyy`*-*`MM`*-*`dd`*`T`*`HH`*:*`mm`*:*`ss`*.*`SSS`*`Z`. update_time_before must be within the last 180 days and the default is the current time., update_time_after: str # The date and time when the dispute was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *`yyyy`*-*`MM`*-*`dd`*`T`*`HH`*:*`mm`*:*`ss`*.*`SSS`*`Z`. update_time_after must be within the last 180 days and the default is the maximum time (180 days) supported.}\n@returns(200) {items: [map], links: [map]} # A successful request returns the HTTP 200 OK status code and a JSON response body that lists disputes with a full or summary set of details. Default is a summary set of details, which shows the dispute_id, reason, status, dispute_amount, create_time, and update_time fields for each dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code.}\n\n@endpoint GET /v1/customer/disputes/{id}\n@desc Show dispute details\n@required {id: str # The ID of the dispute for which to provide the supporting information.}\n@returns(200) {dispute_id: str, create_time: str(ppaas_date_time_v3), update_time: str(ppaas_date_time_v3), disputed_transactions: [map], reason: str, status: str, dispute_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, dispute_asset: map{asset_symbol: str, quantity: str, quantity_in_subunits: str, decimals: int}, fee_policy: map, external_reason_code: str, dispute_outcome: map{outcome_code: str, outcome_reason: str, amount_refunded: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, asset_refunded: map{asset_symbol: str, quantity: str, quantity_in_subunits: str, decimals: int}}, adjudications: [map], money_movements: [map], fund_movements: [map], dispute_life_cycle_stage: str, dispute_channel: str, messages: [map], extensions: map{merchant_contacted: bool, merchant_contacted_outcome: str, merchant_contacted_time: str(ppaas_date_time_v3), merchant_contacted_mode: str, buyer_contacted_time: str(ppaas_date_time_v3), buyer_contacted_channel: str, billing_dispute_properties: map{duplicate_transaction: map{received_duplicate: bool, original_transaction: map}, incorrect_transaction_amount: map{correct_transaction_amount: map, correct_transaction_asset: map, correct_transaction_time: str(ppaas_date_time_v3)}, payment_by_other_means: map{charge_different_from_original: bool, received_duplicate: bool, payment_method: str, payment_instrument_suffix: str}, credit_not_processed: map{issue_type: str, expected_refund: map, cancellation_details: map, product_details: map, service_details: map, agreed_refund_details: map}, canceled_recurring_billing: map{expected_refund: map, cancellation_details: map}}, merchandize_dispute_properties: map{issue_type: str, product_details: map{description: str, product_received: str, product_received_time: str(ppaas_date_time_v3), expected_delivery_date: str(ppaas_date_time_v3), sub_reasons: [str], purchase_url: str(uri), return_details: map}, service_details: map{description: str, service_started: str, note: str, sub_reasons: [str], purchase_url: str(uri)}, cancellation_details: map{cancellation_date: str(ppaas_date_time_v3), cancellation_number: str, cancelled: bool, cancellation_mode: str}, return_shipping_address: map{address_line_1: str, address_line_2: str, address_line_3: str, admin_area_4: str, admin_area_3: str, admin_area_2: str, admin_area_1: str, postal_code: str, country_code: str(ppaas_common_country_code_v2), address_details: map}}, reported_source: str}, evidences: [map], buyer_response_due_date: str(ppaas_date_time_v3), seller_response_due_date: str(ppaas_date_time_v3), offer: map{buyer_requested_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, seller_offered_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, offer_type: str, history: [map]}, refund_details: map{allowed_refund_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}}, communication_details: map{email: str(ppaas_common_email_address_v2), note: str, time_posted: str(ppaas_date_time_v3)}, supporting_info: [map], allowed_response_options: map{acknowledge_return_item: map{acknowledgement_types: [str]}, accept_claim: map{accept_claim_types: [str]}, make_offer: map{offer_types: [str]}}, links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that shows dispute details.\n@errors {500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n\n@endpoint PATCH /v1/customer/disputes/{id}\n@desc Partially update dispute\n@required {id: str # The ID of the dispute for which to provide the supporting information.}\n@returns(202) {links: [map]} # 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 Clients can choose webhook option as well to receive dispute update notification.\n@returns(204) A successful request returns the HTTP `204 No Content` status code with no JSON response body.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code., 422: The requested action could not be completed. The request returns the HTTP `422 Unprocessable Entity` status code., 500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n\n@endpoint POST /v1/customer/disputes/{id}/provide-evidence\n@desc Provide evidence\n@required {id: str # The ID of the dispute for which to provide the supporting information.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code.}\n\n@endpoint POST /v1/customer/disputes/{id}/appeal\n@desc Appeal dispute\n@required {id: str # The ID of the dispute for which to provide the supporting information.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code.}\n\n@endpoint POST /v1/customer/disputes/{id}/accept-claim\n@desc Accept claim\n@required {id: str # The ID of the dispute for which to provide the supporting information.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code.}\n\n@endpoint POST /v1/customer/disputes/{id}/adjudicate\n@desc Settle dispute\n@required {id: str # The ID of the dispute for which to provide the supporting information., adjudication_outcome: str(BUYER_FAVOR/SELLER_FAVOR) # The outcome of the adjudication.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code., 422: The requested action could not be completed. The request returns the HTTP `422 Unprocessable Entity` status code., 500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n@example_request {\"adjudication_outcome\":\"BUYER_FAVOR\"}\n\n@endpoint POST /v1/customer/disputes/{id}/require-evidence\n@desc Update dispute status\n@required {id: str # The ID of the dispute for which to provide the supporting information., action: str(BUYER_EVIDENCE/SELLER_EVIDENCE) # The action. Indicates whether the state change enables the customer or merchant to submit evidence.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code., 422: The requested action could not be completed. The request returns the HTTP `422 Unprocessable Entity` status code., 500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n@example_request {\"note\":\"Escalating to PayPal claim for resolution.\"}\n\n@endpoint POST /v1/customer/disputes/{id}/escalate\n@desc Escalate dispute to claim\n@required {id: str # The ID of the dispute for which to provide the supporting information.}\n@optional {note: str # The notes about the escalation of the dispute to a claim., buyer_escalation_reason: any}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code., 422: The requested action could not be completed. The request returns the HTTP `422 Unprocessable Entity` status code., 500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n@example_request {\"action\":\"BUYER_EVIDENCE\"}\n\n@endpoint POST /v1/customer/disputes/{id}/send-message\n@desc Send message about dispute to other party\n@required {id: str # The ID of the dispute for which to provide the supporting information.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code., 422: The requested action could not be completed. The request returns the HTTP `422 Unprocessable Entity` status code., 500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n\n@endpoint POST /v1/customer/disputes/{id}/make-offer\n@desc Make offer to resolve dispute\n@required {id: str # The ID of the dispute for which to provide the supporting information., note: str # The merchant's notes about the offer., offer_type: str(REFUND/REFUND_WITH_RETURN/REFUND_WITH_REPLACEMENT/REPLACEMENT_WITHOUT_REFUND) # The merchant-proposed offer type for the dispute.}\n@optional {offer_amount: map{currency_code!: str(ppaas_common_currency_code_v2), value!: str} # The currency and amount for a financial transaction, such as a balance or payment due., return_shipping_address: map{address_line_1: str, address_line_2: str, address_line_3: str, admin_area_4: str, admin_area_3: str, admin_area_2: str, admin_area_1: str, postal_code: str, country_code!: str(ppaas_common_country_code_v2), address_details: map} # 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)., invoice_id: str # 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.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code., 422: The requested action could not be completed. The request returns the HTTP `422 Unprocessable Entity` status code., 500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n@example_request {\"note\":\"Offer refund with replacement item.\",\"offer_amount\":{\"currency_code\":\"USD\",\"value\":\"23\"},\"offer_type\":\"REFUND_WITH_REPLACEMENT\"}\n\n@endpoint POST /v1/customer/disputes/{id}/accept-offer\n@desc Accept offer to resolve dispute\n@required {id: str # The ID of the dispute for which to provide the supporting information.}\n@optional {note: str # The customer notes about accepting of offer. PayPal can but the merchant cannot view these notes.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@returns(202) {links: [map]} # 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.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code., 422: The requested action could not be completed. The request returns the HTTP `422 Unprocessable Entity` status code., 500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n@example_request {\"note\":\"I am ok with the refund offered.\"}\n\n@endpoint POST /v1/customer/disputes/{id}/deny-offer\n@desc Deny offer to resolve dispute\n@required {id: str # The ID of the dispute for which to provide the supporting information., note: str # The customer notes about the denial of offer. PayPal can but the merchant cannot view these notes.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code., 422: The requested action could not be completed. The request returns the HTTP `422 Unprocessable Entity` status code., 500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n@example_request {\"note\":\"refund offer is very low.\"}\n\n@endpoint POST /v1/customer/disputes/{id}/acknowledge-return-item\n@desc Acknowledge returned item\n@required {id: str # The ID of the dispute for which to provide the supporting information.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code., 422: The requested action could not be completed. The request returns the HTTP `422 Unprocessable Entity` status code., 500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n\n@endpoint POST /v1/customer/disputes/{id}/provide-supporting-info\n@desc Provide supporting information for dispute\n@required {id: str # The ID of the dispute for which to provide the supporting information.}\n@returns(200) {links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that includes a link to the dispute.\n@errors {400: The request failed due to a validation error. The request returns the HTTP `400 Bad Request` status code., 404: The request failed due to the dispute is not available. The request returns the HTTP `404 Not Found` status code., 422: The requested action could not be completed. The request returns the HTTP `422 Unprocessable Entity` status code., 500: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.}\n\n@end\n"}}