Disputes

Update Dispute

Changed on

Edits a dispute's evidence while it is still editable. When the evidence is ready, send it to the payment processor with POST /disputes/:id/submit.

patch/disputes/{id}

Request

  • Base URL: https://api.whop.com/api/v1
  • URL: https://api.whop.com/api/v1/disputes/{id}
  • Auth: HTTP bearer

Headers

Api-Version-Datestring
Example:2026-10-13-1

Pins the request to a dated API version.

Request body

Example request

{
  "evidence": {
    "access_activity_log": "Vehicle checked in 2026-01-04 09:02, released 2026-01-05 16:40. Signed release on file.",
    "billing_address": "4180 Burnet Rd, Austin, TX 78756, US",
    "cancellation_policy_attachment": {
      "direct_upload_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "id": "file_xxxxxxxxxxxxxx"
    },
    "cancellation_policy_disclosure": "Shown at checkout and again in the booking confirmation email.",
    "customer_communication_attachment": {
      "direct_upload_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "id": "file_xxxxxxxxxxxxxx"
    },
    "customer_email_address": "marcus@shinetime.example",
    "customer_name": "Dana Whitfield",
    "documents": [
      {
        "document_type": "return_policy",
        "id": "file_xxxxxxxxxxxxxx"
      }
    ],
    "notes": "Two-day ceramic coating completed and collected. Before and after photos attached.",
    "product_description": "Two-stage paint correction with a three-year ceramic coating.",
    "refund_policy_attachment": {
      "direct_upload_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "id": "file_xxxxxxxxxxxxxx"
    },
    "refund_policy_disclosure": "Linked from the booking page and accepted at checkout.",
    "refund_refusal_explanation": "Work was completed and the vehicle collected, so the deposit is non-refundable.",
    "service_date": "2026-01-01",
    "uncategorized_attachment": {
      "direct_upload_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "id": "file_xxxxxxxxxxxxxx"
    }
  }
}

Response

dispute updated

account_idstring nullable required

The account the dispute was filed against, prefixed biz_.

amountnumber required

The disputed amount, in whole units of currency.

created_atstring required

When the dispute was opened, as an ISO 8601 timestamp.

currencystring required

Three-letter ISO currency code of the disputed amount.

evidence_due_atstring nullable required

The deadline to submit evidence, as an ISO 8601 timestamp. null when the network already auto-resolved the dispute (Visa RDR) with no evidence round, or when the processor hasn't reported a deadline for this dispute.

evidence_editableboolean required

Whether evidence can still be changed and submitted.

evidence_locked_reason'submitted' | 'response_window_closed' | 'not_contestable' | 'null' nullable required

Why evidence can no longer be edited. null while evidence_editable is true.

evidence_submitted_atstring nullable required

When the evidence was submitted to the processor, as an ISO 8601 timestamp.

idstring required

Dispute ID, prefixed dspt_.

inquiryboolean required

Whether this is a pre-dispute inquiry rather than a formal chargeback. Inquiries follow the same lifecycle but move no funds unless one escalates.

plan_idstring nullable required

The variant the disputed payment was made on, prefixed plan_.

product_idstring nullable required

The product the disputed payment was for, prefixed prod_.

reason'fraudulent' | 'unrecognized' | 'declined_authorization' | 'product_not_received' | 'product_unacceptable' | 'subscription_canceled' | 'credit_not_processed' | 'duplicate' | 'processing_error' | 'documentation_request' | 'bank_cannot_process' | 'other' required

Why the customer says they are disputing, normalized across processors and card networks. other covers a processor reason Whop has not categorized yet.

reason_codestring nullable required

The raw card-network or processor reason code, such as 10.4. Informational only — reason is not derived from it.

status'needs_response' | 'warning_needs_response' | 'under_review' | 'warning_under_review' | 'won' | 'lost' | 'prevented' | 'warning_closed' required

Where the dispute stands. needs_response is awaiting evidence, under_review is with the processor, won returned the funds to the seller, lost returned them to the customer, and prevented means the customer was refunded before any ruling, so it settles like lost. The warning_ statuses are the same stages for an inquiry, which moves no funds. A dispute past its evidence_due_at reports under_review — the window to respond has closed.

updated_atstring required

When the dispute was last changed, as an ISO 8601 timestamp.

Example response

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "amount": 150,
  "buyer": {
    "email": "marcus@shinetime.example",
    "member_id": "mber_xxxxxxxxxxxxxx",
    "name": "Dana Whitfield",
    "user_id": "user_xxxxxxxxxxxxxx",
    "username": "danawhitfield"
  },
  "created_at": "2026-01-01T12:00:00.000Z",
  "currency": "usd",
  "evidence": {
    "access_activity_log": "Vehicle checked in 2026-01-04 09:02, released 2026-01-05 16:40. Signed release on file.",
    "billing_address": "4180 Burnet Rd, Austin, TX 78756, US",
    "cancellation_policy_attachment": {
      "content_type": "image/png",
      "filename": "booking-confirmation-email.png",
      "id": "file_xxxxxxxxxxxxxx",
      "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "cancellation_policy_disclosure": "Shown at checkout and again in the booking confirmation email.",
    "customer_communication_attachment": {
      "content_type": "image/png",
      "filename": "booking-confirmation-email.png",
      "id": "file_xxxxxxxxxxxxxx",
      "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "customer_email_address": "marcus@shinetime.example",
    "customer_name": "Dana Whitfield",
    "documents": [
      {
        "blurhash": "LA6bDXT$E3b:R6i+RibEIWbp%ej1",
        "content_type": "image/png",
        "created_at": "2026-01-01T12:00:00.000Z",
        "document_type": "customer_order_history",
        "filename": "customer-order-history.png",
        "height": 100,
        "id": "file_xxxxxxxxxxxxxx",
        "multipart_upload_urls": [
          {
            "part_number": 1,
            "url": "https://whop-assets-example.s3.amazonaws.com/uploads/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/application.pdf"
          }
        ],
        "object": "file",
        "size": 1024,
        "upload_status": "ready",
        "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "visibility": "public",
        "width": 100
      }
    ],
    "notes": "Two-day ceramic coating completed and collected. Before and after photos attached.",
    "product_description": "Two-stage paint correction with a three-year ceramic coating.",
    "refund_policy_attachment": {
      "content_type": "image/png",
      "filename": "booking-confirmation-email.png",
      "id": "file_xxxxxxxxxxxxxx",
      "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "refund_policy_disclosure": "Linked from the booking page and accepted at checkout.",
    "refund_refusal_explanation": "Work was completed and the vehicle collected, so the deposit is non-refundable.",
    "service_date": "2026-01-01",
    "uncategorized_attachment": {
      "content_type": "image/png",
      "filename": "booking-confirmation-email.png",
      "id": "file_xxxxxxxxxxxxxx",
      "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  },
  "evidence_due_at": "2026-01-01T12:00:00.000Z",
  "evidence_locked_reason": "submitted",
  "evidence_submitted_at": "2026-01-01T12:00:00.000Z",
  "fee": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "id": "dspt_xxxxxxxxxxxxxx",
  "issuer_comments": [
    {
      "received_at": "2026-01-01T12:00:00.000Z",
      "text": "Note: Cardholder states the ceramic coating appointment never took place\nCancellation method: By phone"
    }
  ],
  "line_items": [
    {
      "id": "li_xxxxxxxxxxxxxx",
      "label": "Ceramic Coating Package",
      "plan_id": "plan_xxxxxxxxxxxxxx",
      "plan_title": "Ceramic Coating — Full Vehicle",
      "product_id": "prod_xxxxxxxxxxxxxx",
      "product_title": "Ceramic Coating Package",
      "quantity": 1,
      "subtotal": {
        "amount": "-1234.56",
        "currency": "usd",
        "decimals": 2,
        "display_decimals": 2
      }
    }
  ],
  "payment": {
    "amount": 249,
    "card_brand": "visa",
    "card_last4": "4242",
    "created_at": "2026-01-01T12:00:00.000Z",
    "currency": "usd",
    "id": "pay_xxxxxxxxxxxxxx",
    "payment_instrument": {
      "card": {
        "brand": "visa",
        "exp_month": 10,
        "exp_year": 2031,
        "issuer_identification_number": "41111111",
        "last4": "4242"
      },
      "display_name": "Visa •••• 4242",
      "icons": {
        "card": {
          "dark": {
            "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
            "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
            "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
            "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
          },
          "light": {
            "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
            "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
            "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
            "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
          }
        },
        "square": {
          "dark": {
            "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
            "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
            "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
            "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
          },
          "light": {
            "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
            "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
            "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
            "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
          }
        }
      },
      "payment_method_type": "card"
    },
    "payment_method_type": "card"
  },
  "plan_id": "plan_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "reason": "other",
  "reason_code": "13.1",
  "status": "under_review",
  "updated_at": "2026-01-01T12:00:00.000Z"
}

Changes

  • 507636677fe9Revision changes
    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

  • 8d8dfbc0275fRevision changes
    • info

      added the required property to the response with the status