# PayPal disputes

The report is crucial, offering detailed insights on each PayPal dispute and lifecycle stage. These details are essential for effective dispute management and enhancing customer satisfaction.


  This report uses the created_at as the default parameter for unloading data.

Endpoint: POST /apm-orders/paypal-disputes
Version: 1.0.0
Security: MerchantID

## Header parameters:

  - `merchant` (string, required)
    Unique public key provided upon registration and must be shared for identification purposes.
    Example: "api_pk_7b197...ba108f842"

  - `signature` (string, required)
    Request signature that allows verification of merchant authenticity on the payment gateway server.
    Example: "M2E3OTkyNzcz...xMmExODI4"

## Request fields (application/json):

  - `filter` (string)
    Filtering criteria for the report data.
    Enum: "updated_at", "created_at"

  - `date_from` (string, required)
    Start datetime for the report stated in UTC+0.
    Example: "2025-08-15 11:00:00"

  - `date_to` (string, required)
    End datetime for the report stated in UTC+0.
    Example: "2025-08-18 11:00:00"

  - `limit` (integer)
    Limit value indicates the maximum number of items to be returned.
    Example: 2000

  - `next_page_iterator` (string)
    Pagination helps in managing large datasets by dividing them into smaller, manageable chunks.


  If this value is null, it indicates that all available data has been successfully retrieved by the merchant.
    Example: "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"

## Response 200 fields (application/json):

  - `body` (object) — one of:
    - Success:
      - `disputes` (array, required)
        List of disputes, each containing attributes like identifiers, dates, amounts, currencies, stages, channels, reasons, and status.
      - `disputes.dispute_id` (string, required)
        Unique dispute identifier.
      - `disputes.order_id` (string, required)
        Unique order identifier defined by the merchant.
      - `disputes.subscription_product_id` (string)
        Unique product identifier of the subscription.


   It corresponds to the product_id parameter in subscriptions.
      - `disputes.subscription_service_id` (string)
        Subscription identifier.


   It corresponds to the subscription_id parameter in subscriptions.
      - `disputes.created_at` (string, required)
        Datetime when the dispute was created.
      - `disputes.updated_at` (string, required)
        Datetime when the dispute was updated.
      - `disputes.seller_response_due_date` (string)
        Deadline for submitting a response to the dispute.
      - `disputes.dispute_amount` (integer, required)
        Dispute amount.
      - `disputes.dispute_currency` (string, required)
        Three-letter ISO-4217 currency code of the dispute.
      - `disputes.dispute_life_cycle_stage` (string, required)
        Stage in the dispute lifecycle.
        Enum: "INQUIRY", "CHARGEBACK", "PRE_ARBITRATION", "ARBITRATION"
      - `disputes.dispute_channel` (string, required)
        Indicates the channel by which PayPal dispute has been received.
        Enum: "INTERNAL", "EXTERNAL", "ALERT"
      - `disputes.dispute_create_time` (string, required)
        Datetime when the dispute was created.
      - `disputes.dispute_update_time` (string, required)
        Datetime when the dispute was updated.
      - `disputes.dispute_outcome` (string)
        Outcome of the dispute.
        Enum: "RESOLVED_BUYER_FAVOUR", "RESOLVED_SELLER_FAVOUR", "RESOLVED_WITH_PAYOUT", "CANCELED_BY_BUYER", "NONE"
      - `disputes.reason` (string, required)
        Reason for the received dispute.
        Enum: "MERCHANDISE_OR_SERVICE_NOT_RECEIVED", "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED", "UNAUTHORISED", "CREDIT_NOT_PROCESSED", "DUPLICATE_TRANSACTION", "INCORRECT_AMOUNT", "PAYMENT_BY_OTHER_MEANS", "CANCELED_RECURRING_BILLING", "PROBLEM_WITH_REMITTANCE", "OTHER"
      - `disputes.status` (string, required)
        Status of the PayPal dispute.
        Enum: "OPEN", "WAITING_FOR_BUYER_RESPONSE", "WAITING_FOR_SELLER_RESPONSE", "UNDER_REVIEW", "RESOLVED", "OTHER"
      - `disputes.represented_by` (string)
        Indicates which party has provided the defense document for dispute representment.
        Enum: "merchant", "automation"
      - `disputes.customer_account_id` (string)
        Unique customer identifier defined by the merchant.
      - `disputes.customer_email` (string)
        Customer's email address.
      - `metadata` (object, required)
        Metadata object containing pagination and count information.
      - `metadata.next_page_iterator` (string, required)
        Pagination helps in managing large datasets by dividing them into smaller, manageable chunks.


  If this value is null, it indicates that all available data has been successfully retrieved by the merchant.
      - `metadata.count` (integer, required)
        Number of disputes on the page.
    - Authentication failed:
      - `error` (object, required)
        Error object.
      - `error.code` (string, required)
        Unauthorized access due to invalid credentials.
        Example: "1.01"
      - `error.messages` (array, required)
        Array of error messages applied to the decline payment.
        Example: ["Authentication failed"]