Disputes - Whop Docs

A Dispute is a chargeback a customer files against a payment through their bank, or an inquiry that may become one. 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.

Endpoints

Endpoint	Request
List Disputes	GET `/disputes`
Retrieve Dispute	GET `/disputes/{id}`
Retrieve Dispute Summary	GET `/disputes/summary`
Submit Dispute	POST `/disputes/{id}/submit`
Upload Dispute Evidence	POST `/disputes/{id}/upload_evidence`
Update Dispute	PATCH `/disputes/{id}`

Attributes

string

required

Dispute ID, prefixed dspt_.

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

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, in the processor’s own evidence vocabulary. return_policy, cancellation_policy, and terms_of_service are the seller’s policy documents — uploading one overrides the account’s copy for this dispute (return_policy, cancellation_policy, and customer_communication also override the matching fixed evidence slot). shipping_policy is the seller’s shipping terms. customer_communication is correspondence with the buyer — a support thread or chat log. product_image is a photo of the product or service the buyer received. physical_fulfillment is proof a physical order shipped and arrived; digital_fulfillment is proof the buyer accessed a digital product. customer_order_history is the buyer’s past orders with this seller; prior_transactions is their broader payment history across the platform, for a fraud defense. customer_session is checkout forensics — IP, device fingerprint, AVS/CVV, 3D Secure result. subscription is membership lifecycle evidence — renewals, cancellation, reminders sent.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

string | null

required

The original filename, including its extension.

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.

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: a permanent CDN URL for public files, a signed expiring URL for private ones. null until the upload has finished.

string

required

public files are served via an unsigned CDN URL; private files via a signed, expiring URL.Available options: public, private

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 seller, in the currency it was collected in. null when no fee was charged, such as for an inquiry or a Visa RDR resolution.

Properties

string

required

The amount in major units, as an exact decimal string — "10.00" is ten dollars. A string so no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount CARRIES — 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 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 plan_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 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.

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 — "10.00" is ten dollars. A string so no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount CARRIES — the precision the charge itself runs at.

integer

required

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 when it was a card. Null when the payment names no method.

Properties

object | null

required

Card payments only: the card’s network, last four, and issuer identification number.

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

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 variant the disputed payment was made on, prefixed plan_.

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

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.Available options: needs_response, warning_needs_response, under_review, warning_under_review, won, lost, prevented, warning_closed

string

required

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

Dispute

{
	"id": "dspt_xxxxxxxxxxxxx",
	"account_id": "biz_xxxxxxxxxxxxxx",
	"amount": 49.99,
	"buyer": {
		"email": "alex@example.com",
		"member_id": "mem_xxxxxxxxxxxxx",
		"name": "Alex Rivera",
		"user_id": "user_xxxxxxxxxxxxx",
		"username": "alex"
	},
	"created_at": "2026-06-01T12:00:00Z",
	"currency": "usd",
	"evidence": {
		"access_activity_log": "2026-05-02 14:11 UTC signed in and opened the course; 2026-05-04 09:32 UTC downloaded lesson materials",
		"billing_address": "123 Main St, Austin, TX 78701, US",
		"cancellation_policy_attachment": null,
		"cancellation_policy_disclosure": "Shown on the checkout page beneath the pay button.",
		"customer_communication_attachment": {
			"id": "att_xxxxxxxxxxxxx",
			"content_type": "application/pdf",
			"filename": "support-thread.pdf",
			"platform": false,
			"url": "https://assets.whop.com/uploads/att_xxxxxxxxxxxxx/support-thread.pdf"
		},
		"customer_email_address": "alex@example.com",
		"customer_name": "Alex Rivera",
		"notes": "Customer accessed the product for four weeks before disputing.",
		"product_description": "Monthly membership to the Pickaxe trading community, including the full course library.",
		"refund_policy_attachment": {
			"id": null,
			"content_type": "application/pdf",
			"filename": "refund-policy.pdf",
			"platform": true,
			"url": "https://whop.com/policies/refund-policy.pdf"
		},
		"refund_policy_disclosure": "Linked in the order confirmation email and on the checkout page.",
		"refund_refusal_explanation": "Refund was refused because the membership had been used past the 7-day refund window.",
		"service_date": "2026-05-01",
		"uncategorized_attachment": null,
		"documents": [
			{
				"id": "file_xxxxxxxxxxxxxx",
				"object": "file",
				"document_type": "product_image",
				"filename": "before-and-after-coating.png",
				"content_type": "image/png",
				"size": 48213,
				"url": "https://cdn.whop.com/attachments/before-and-after-coating.png",
				"upload_status": "ready",
				"visibility": "private",
				"created_at": "2026-06-01T12:00:00Z"
			}
		]
	},
	"evidence_due_at": "2026-06-15T00:00:00Z",
	"evidence_editable": true,
	"evidence_locked_reason": null,
	"evidence_submitted_at": null,
	"fee": {
		"amount": "15.00",
		"currency": "usd",
		"decimals": 2,
		"display_decimals": 2
	},
	"inquiry": false,
	"issuer_comments": [
		{
			"received_at": "2026-06-01T12:00:00Z",
			"text": "Cardholder states they did not authorize this transaction."
		}
	],
	"payment": {
		"id": "pay_xxxxxxxxxxxxx",
		"amount": 49.99,
		"card_brand": "visa",
		"card_last4": "4242",
		"created_at": "2026-05-01T09:30:00Z",
		"currency": "usd",
		"payment_method_type": "card",
		"payment_processor": null,
		"payment_instrument": {
			"payment_method_type": "card",
			"display_name": "Visa •••• 4242",
			"icons": {
				"square": {
					"light": {
						"svg": "https://content.whop.com/payment_methods/visa/square_light.svg",
						"png_1x": "https://content.whop.com/payment_methods/visa/square_light_32.png",
						"png_2x": "https://content.whop.com/payment_methods/visa/square_light_64.png",
						"png_4x": "https://content.whop.com/payment_methods/visa/square_light_128.png"
					},
					"dark": {
						"svg": "https://content.whop.com/payment_methods/visa/square_dark.svg",
						"png_1x": "https://content.whop.com/payment_methods/visa/square_dark_32.png",
						"png_2x": "https://content.whop.com/payment_methods/visa/square_dark_64.png",
						"png_4x": "https://content.whop.com/payment_methods/visa/square_dark_128.png"
					}
				},
				"card": {
					"light": {
						"svg": "https://content.whop.com/payment_methods/visa/card_light.svg",
						"png_1x": "https://content.whop.com/payment_methods/visa/card_light_30.png",
						"png_2x": "https://content.whop.com/payment_methods/visa/card_light_60.png",
						"png_4x": "https://content.whop.com/payment_methods/visa/card_light_120.png"
					},
					"dark": {
						"svg": "https://content.whop.com/payment_methods/visa/card_dark.svg",
						"png_1x": "https://content.whop.com/payment_methods/visa/card_dark_30.png",
						"png_2x": "https://content.whop.com/payment_methods/visa/card_dark_60.png",
						"png_4x": "https://content.whop.com/payment_methods/visa/card_dark_120.png"
					}
				}
			},
			"card": {
				"brand": "visa",
				"last4": "4242",
				"issuer_identification_number": "41111111",
				"exp_month": 11,
				"exp_year": 2030
			},
			"installment_count": null
		}
	},
	"line_items": [
		{
			"id": "li_xxxxxxxxxxxxx",
			"label": "Ceramic Coating Package",
			"plan_id": "plan_xxxxxxxxxxxxx",
			"plan_title": "One-time",
			"product_id": "prod_xxxxxxxxxxxxx",
			"product_title": "Ceramic Coating Package",
			"quantity": 1,
			"sku": "CERAMIC-COAT-3YR",
			"subtotal": {
				"amount": "299.00",
				"currency": "usd",
				"decimals": 2,
				"display_decimals": 2
			}
		}
	],
	"plan_id": "plan_xxxxxxxxxxxxx",
	"product_id": "prod_xxxxxxxxxxxxx",
	"reason": "fraudulent",
	"reason_code": "10.4",
	"status": "needs_response",
	"updated_at": "2026-06-01T12:00:00Z"
}

​Endpoints

​Attributes

Endpoints

Attributes