Skip to main content
It carries the disputed payment, a deadline to respond, your evidence, and the outcome once the processor rules. Use the Disputes API to list disputes, edit the evidence packet while a dispute is still contestable, and submit it for review, or accept a chargeback you don’t want to contest.

Endpoints

Attributes

string
required
Dispute ID, prefixed dspt_.
boolean
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.
string | null
required
The account the dispute was filed against, prefixed biz_.
number
required
The disputed amount, in whole units of currency.
object
required
The customer who filed the dispute.

Properties

string | null
required
The customer’s email address. Requires the member:email:read scope; null without it.
string | null
required
The customer’s member row on the account, prefixed mem_.
string | null
required
The customer’s display name.
string | null
required
The customer’s user ID, prefixed user_. null for a guest checkout.
string | null
required
The customer’s Whop username.
string
required
When the dispute was opened, as an ISO 8601 timestamp.
string
required
Three-letter ISO currency code of the disputed amount.
object
required
The evidence packet sent to the processor to contest the dispute.

Properties

string | null
required
Log of the customer’s access to the product, such as sign-in or download activity.
string | null
required
The billing address the customer provided at checkout.
object | null
required
The cancellation policy document. Defaults to the account’s cancellation policy, then its terms of service, then its return policy, then Whop’s platform policy.

Properties

string | null
required
The attachment’s ID. null for a Whop-hosted policy, which is not an uploaded file.
string | null
required
The uploaded file’s MIME type.
string | null
required
The uploaded file’s name.
boolean
required
Whether this is Whop’s own hosted policy, standing in because the seller uploaded none. Sending it back on a PATCH changes nothing.
string | null
required
A URL to download the attachment.
string | null
required
How the cancellation policy was shown to the customer before purchase.
object | null
required
Correspondence with the customer, or proof they used the product.

Properties

string | null
required
The attachment’s ID. null for a Whop-hosted policy, which is not an uploaded file.
string | null
required
The uploaded file’s MIME type.
string | null
required
The uploaded file’s name.
boolean
required
Whether this is Whop’s own hosted policy, standing in because the seller uploaded none. Sending it back on a PATCH changes nothing.
string | null
required
A URL to download the attachment.
string | null
required
The email address the customer used at checkout.
string | null
required
The customer’s name as given at checkout.
object[]
required
Additional evidence documents, beyond the four fixed slots — set via evidence.documents on PATCH /disputes/\{id}. Each rides into the submitted packet under its document_type.

Properties

string
required
The file’s ID, prefixed file_.
string | null
required
BlurHash placeholder for an image or video. Null when unavailable or removed by moderation.
string | null
required
The uploaded file’s MIME type. Uploads are restricted to the types the processor accepts, and rejected without one — never null.Available options: application/pdf, application/json, image/jpeg, image/png, image/webp
string
required
When the file was created, as an ISO 8601 timestamp.
string
required
What this document proves. return_policy, cancellation_policy and terms_of_service are the seller’s policy documents. A policy document replaces the account’s copy for this dispute. return_policy, cancellation_policy and customer_communication also replace the matching fixed evidence slot. shipping_policy is the seller’s shipping terms. customer_communication is correspondence with the buyer, such as a support thread or chat log. product_image is a photo of the product or service the buyer received. physical_fulfillment is proof that a physical order shipped and arrived. digital_fulfillment is proof that the buyer accessed a digital product. customer_order_history is the buyer’s past orders with this seller. prior_transactions is the buyer’s payment history across the platform, for a fraud defense. customer_session is checkout data, such as IP address, device fingerprint, AVS and CVV results, and the 3D Secure result. subscription is membership lifecycle evidence, such as renewals, cancellation and reminders sent. complete_evidence is the seller’s whole response as one PDF of at most 19 pages, and it must be the only document. Whop sends a complete_evidence document to the processor in place of every other evidence field, attachment and document.Available options: return_policy, shipping_policy, cancellation_policy, terms_of_service, physical_fulfillment, customer_order_history, product_image, prior_transactions, customer_session, digital_fulfillment, subscription, customer_communication, complete_evidence
number | null
required
Audio or video duration in seconds. Null when unavailable or removed by moderation.
string | null
required
The original filename, including its extension.
integer | null
required
Image or video height in pixels. Null when unavailable or removed by moderation.
integer | null
The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.
string | null
The ID of the multipart upload, passed back to complete. Present only on create, and only for multipart uploads.
object[] | null
The presigned URL for each part. Present only on create, and only for multipart uploads.

Properties

integer
required
The 1-based index of this part within the multipart upload.
string
required
The presigned URL to PUT this part’s bytes to.
string
required
The type of this object, always file.
boolean
required
Whether moderation removed the file. When true, url serves a replacement image. filename, size and content_type still describe the original file.
integer | null
required
The file size in bytes. null until the upload has finished.
object
Headers to send with the upload PUT. Present only on create.
string
required
Where the file is in its upload lifecycle.Available options: pending, processing, ready, failed
string | null
Presigned URL to PUT the file’s bytes to. Present only on create, and only for single-part uploads.
string | null
required
A URL to download the file. Public files get a permanent CDN URL, and private files get a signed URL that expires. null until the upload has finished. When moderation removes the file, a replacement image URL.
string
required
public files are served from an unsigned CDN URL. private files are served from a signed URL that expires.Available options: public, private
string | null
required
Audio waveform URL. Null when unavailable or removed by moderation.
integer | null
required
Image or video width in pixels. Null when unavailable or removed by moderation.
string | null
required
Any additional context for the processor reviewing the dispute.
string | null
required
What the customer purchased, in the seller’s own words.
object | null
required
The refund policy document. Defaults to the account’s return policy, then its terms of service, then Whop’s platform policy.

Properties

string | null
required
The attachment’s ID. null for a Whop-hosted policy, which is not an uploaded file.
string | null
required
The uploaded file’s MIME type.
string | null
required
The uploaded file’s name.
boolean
required
Whether this is Whop’s own hosted policy, standing in because the seller uploaded none. Sending it back on a PATCH changes nothing.
string | null
required
A URL to download the attachment.
string | null
required
How the refund policy was shown to the customer before purchase.
string | null
required
Why a refund was refused, when one was requested and denied.
string | null
required
When the product or service was delivered.
object | null
required
Supporting evidence that does not fit the other categories.

Properties

string | null
required
The attachment’s ID. null for a Whop-hosted policy, which is not an uploaded file.
string | null
required
The uploaded file’s MIME type.
string | null
required
The uploaded file’s name.
boolean
required
Whether this is Whop’s own hosted policy, standing in because the seller uploaded none. Sending it back on a PATCH changes nothing.
string | null
required
A URL to download the attachment.
string | null
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.
boolean
required
Whether evidence can still be changed and submitted.
string | null
required
Why evidence can no longer be edited. null while evidence_editable is true.Available options: submitted, response_window_closed, not_contestable
string | null
required
When the evidence was submitted to the processor, as an ISO 8601 timestamp.
object | null
required
The dispute fee charged to the account, in the currency it was collected in. null when fee_charged is false.

Properties

string
required
The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.
string
required
Three-letter ISO 4217 currency code, lowercase.
integer
required
How many decimal places the amount carries. This is the precision the charge itself runs at.
integer
required
How many decimal places to SHOW. Usually equal to decimals, and deliberately not always: COP is charged in centavos but written in whole pesos, so it is 2 and 0. Format the number in your own locale using this.
boolean
required
Whether Whop charged the account a dispute fee for this one. false when the payment was fully refunded before the dispute was opened, for a Visa RDR resolution, and for an inquiry.
boolean
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.
object[]
required
What the card issuer said when filing the dispute. Only populated when the issuer provides them, and listed in the order they were received.

Properties

string | null
required
When the comment was received, as an ISO 8601 timestamp.
string
required
What the issuer wrote, as received.
object[]
required
Everything the disputed payment charged for, in purchase order. product_id and variant_id name the first of these; a cart’s later items appear only here. A payment made before items were recorded lists the single item its variant implies. Empty when the payment is not linked to a variant.

Properties

string | null
required
Line item ID, prefixed li_. Null when the payment predates item snapshots and the item is read from the payment’s variant.
string | null
required
The item’s name as shown at checkout (the product title, else the variant title).
string | null
required
The product the variant belongs to, prefixed prod_. On a payment that predates item snapshots this falls back to the variant’s product, so it can be set where the parent’s own product_id is null. Null for a variant with no product.
string | null
required
The product’s current title, or null when the item has no product.
number
required
How many units were bought.
string | null
required
The variant’s stock keeping unit, free text set by the seller (e.g. TSHIRT-LARGE-BLUE). Accounts with billing-reason SKU suffixes enabled receive it stamped with why the charge happened: -S for a first subscription charge, -R for a renewal, -C for a one-time purchase, -U when the payment’s own metadata carries upsell: true, -F when nothing was charged. Other billing reasons carry the bare SKU. null when the variant has no SKU or has been deleted.
object | null
required
The recorded amount for this item’s full quantity, before discounts, tax, and fees, in its purchase currency. Returns null when no item amount was recorded.

Properties

string
required
The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.
string
required
Three-letter ISO 4217 currency code, lowercase.
integer
required
How many decimal places the amount carries. This is the precision the charge itself runs at.
integer
required
How many decimal places to SHOW. Usually equal to decimals, and deliberately not always: COP is charged in centavos but written in whole pesos, so it is 2 and 0. Format the number in your own locale using this.
string | null
required
The variant bought, prefixed plan_. Null when the variant has since been deleted.
string | null
required
The variant’s current title, or null when the variant has been deleted or has no title.
object
required
The payment being disputed.

Properties

string
required
Payment ID, prefixed pay_.
number | null
required
What the customer was charged, in whole units of the payment’s currency.
string | null
required
Card brand, when the customer paid by card.
string | null
required
Last four digits of the card, when the customer paid by card.
string
required
When the payment was made, as an ISO 8601 timestamp.
string | null
required
Three-letter ISO currency code of the payment. Can differ from the dispute’s currency when the processor settles in another currency.
object | null
required
The instrument this payment was made with, shaped for display: the method type, a buyer-facing name, the standard icon set, and the card facts, including the network transaction id the account uses for the card, when it was a card. Null when the payment names no method.

Properties

object | null
required
Card, Apple Pay, and Google Pay payments only: the card’s network, last four, issuer identification number, expiry, and network transaction id.

Properties

string | null
required
The network identifier (visa, amex, …), matching card.networks entries and saved card payment methods. Null when the vault did not record the network.
number | null
required
The card’s expiry month, 1 to 12. Null when the vault did not record it.
number | null
required
The card’s four-digit expiry year. Null when the vault did not record it.
string | null
required
The issuer identification number, also called the BIN: the card’s leading six or eight digits, which identify the issuing bank. Null when the processor did not report it.
string | null
required
The card’s last four digits, when captured.
string | null
required
The network transaction id this account uses for the card. It’s this account’s own id, from its first customer-present charge or verification on the card, when Whop has one. Otherwise it’s an earlier network transaction id for this card, which can come from another account’s transaction or be one brought with the card. Cite it as the prior transaction on a later merchant-initiated charge of this card at this account. Null until there is one. A webhook sent as a payment is first recorded can carry null, so retrieve the payment to read it.
string
required
Buyer-facing instrument name — “Visa •••• 4242” when the card surfaced, else the method’s own name (“Klarna”).
object
required
The standard icon set: square and card shapes, each in light and dark colorways.

Properties

object
required
The credit-card-proportioned tile (48x30).

Properties

object
required
The colorway for dark surfaces.

Properties

string
required
Raster fallback at the shape’s native size.
string
required
Raster fallback at double density.
string
required
Raster fallback at quadruple density.
string
required
The vector file. Prefer this everywhere SVG renders.
object
required
The colorway for light surfaces.

Properties

string
required
Raster fallback at the shape’s native size.
string
required
Raster fallback at double density.
string
required
Raster fallback at quadruple density.
string
required
The vector file. Prefer this everywhere SVG renders.
object
required
The square tile (32x32).

Properties

object
required
The colorway for dark surfaces.

Properties

string
required
Raster fallback at the shape’s native size.
string
required
Raster fallback at double density.
string
required
Raster fallback at quadruple density.
string
required
The vector file. Prefer this everywhere SVG renders.
object
required
The colorway for light surfaces.

Properties

string
required
Raster fallback at the shape’s native size.
string
required
Raster fallback at double density.
string
required
Raster fallback at quadruple density.
string
required
The vector file. Prefer this everywhere SVG renders.
number | null
required
Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.
string
required
The payment method type identifier, e.g. card, klarna, apple_pay.
string | null
required
How the customer paid, such as card or paypal.
string | null
required
Deprecated: no longer populated. Always null. DEPRECATED: No longer populated. Always null.
string | null
required
The product the disputed payment was for, prefixed prod_.
string
required
Why the customer says they are disputing, normalized across processors and card networks. other covers a processor reason Whop has not categorized yet.Available options: fraudulent, unrecognized, declined_authorization, product_not_received, product_unacceptable, subscription_canceled, credit_not_processed, duplicate, processing_error, documentation_request, bank_cannot_process, other
string | null
required
The raw card-network or processor reason code, such as 10.4. Informational only — reason is not derived from it.
string
required
needs_response awaits evidence (after a processor refused a filing, submission_failure_reason says why); generating_response has evidence with the processor, not yet accepted; under_review is with the processor; won/lost are the rulings; prevented settles like lost. warning_ statuses are the inquiry tiers. Past evidence_due_at an open one reports under_review.Available options: needs_response, warning_needs_response, under_review, warning_under_review, generating_response, won, lost, prevented, warning_closed
string | null
required
Why the payment processor refused the last filing, in plain English, while the dispute is back in needs_response. Fix what it names and submit again. Only on retrieve: dispute.updated reports the move back to needs_response, then read this here.
string
required
When the dispute was last changed, as an ISO 8601 timestamp.
string | null
required
The variant the disputed payment was made on, prefixed plan_.
Dispute