Disputes

Upload Dispute Evidence

Changed on

Replaces the full set of uploaded evidence documents on a dispute, beyond the four fixed evidence slots. Prefer PATCH /disputes/:id with evidence.documents, which does the same replace alongside every other evidence field in one call.

post/disputes/{id}/upload_evidence

Request

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

Headers

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

Pins the request to a dated API version.

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

Example request

{
  "documents": [
    {
      "document_type": "return_policy",
      "id": "file_xxxxxxxxxxxxxx"
    }
  ]
}

Response

evidence documents attached

acceptableboolean required

Whether the dispute can be conceded to the customer with POST /disputes/{id}/accept. True only for a chargeback still awaiting a response, before evidence_due_at, whose payment processor supports accepting disputes. Inquiries are never acceptable.

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

  • 54dbb42f6781Revision changes
    • info

      added the required property to the response with the status

  • 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