Disputes

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}
Update Dispute	PATCH /disputes/{id}
Submit Dispute	POST /disputes/{id}/submit
Upload Dispute Evidence	POST /disputes/{id}/upload_evidence
Retrieve Dispute Summary	GET /disputes/summary

Attributes

id · string · required

Dispute ID, prefixed dspt_.

account_id · string | null · required

The account the dispute was filed against, prefixed biz_.

amount · number · required

The disputed amount, in whole units of currency.

buyer · object | null · required

The customer who filed the dispute.

Properties

email · string | null · required

The customer’s email address. Requires the member:email:read scope; null without it.

member_id · string | null · required

The customer’s member row on the account, prefixed mem_.

name · string | null · required

The customer’s display name.

user_id · string | null · required

The customer’s user ID, prefixed user_. null for a guest checkout.

username · string | null · required

The customer’s Whop username.

created_at · string · required

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

currency · string · required

Three-letter ISO currency code of the disputed amount.

evidence · object · required

The evidence packet sent to the processor to contest the dispute.

Properties

access_activity_log · string | null · required

Log of the customer’s access to the product, such as sign-in or download activity.

billing_address · string | null · required

The billing address the customer provided at checkout.

cancellation_policy_attachment · object | null · required

The cancellation policy document. Falls back to Whop’s platform policy when the seller has not uploaded their own.

Properties

id · string | null · required

The attachment’s ID. null for a Whop-hosted policy, which is not an uploaded file.

content_type · string | null · required

The uploaded file’s MIME type.

filename · string | null · required

The uploaded file’s name.

platform · 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.

url · string | null · required

A URL to download the attachment.

cancellation_policy_disclosure · string | null · required

How the cancellation policy was shown to the customer before purchase.

customer_communication_attachment · object | null · required

Correspondence with the customer, or proof they used the product.

Properties

id · string | null · required

The attachment’s ID. null for a Whop-hosted policy, which is not an uploaded file.

content_type · string | null · required

The uploaded file’s MIME type.

filename · string | null · required

The uploaded file’s name.

platform · 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.

url · string | null · required

A URL to download the attachment.

customer_email_address · string | null · required

The email address the customer used at checkout.

customer_name · string | null · required

The customer’s name as given at checkout.

documents · object[] · required

Additional evidence documents uploaded through POST /disputes/\{id}/upload_evidence, beyond the four fixed slots. Each rides into the submitted packet under its document_type.

Properties

id · string · required

The attachment’s ID, prefixed file_.

content_type · string | null · required

The uploaded file’s MIME type. Uploads are restricted to the types the processor accepts.

Available options: application/pdf, application/json, image/jpeg, image/png, image/webp

document_type · string · required

What kind of evidence the document is.

Available options: return_policy, shipping_policy, physical_fulfillment, customer_order_history, product_image, prior_transactions, customer_session, digital_fulfillment, subscription

filename · string | null · required

The uploaded file’s name.

url · string | null · required

A URL to download the document.

notes · string | null · required

Any additional context for the processor reviewing the dispute.

product_description · string | null · required

What the customer purchased, in the seller’s own words.

refund_policy_attachment · object | null · required

The refund policy document. Falls back to Whop’s platform policy when the seller has not uploaded their own.

Properties

id · string | null · required

The attachment’s ID. null for a Whop-hosted policy, which is not an uploaded file.

content_type · string | null · required

The uploaded file’s MIME type.

filename · string | null · required

The uploaded file’s name.

platform · 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.

url · string | null · required

A URL to download the attachment.

refund_policy_disclosure · string | null · required

How the refund policy was shown to the customer before purchase.

refund_refusal_explanation · string | null · required

Why a refund was refused, when one was requested and denied.

service_date · string | null · required

When the product or service was delivered.

uncategorized_attachment · object | null · required

Supporting evidence that does not fit the other categories.

Properties

id · string | null · required

The attachment’s ID. null for a Whop-hosted policy, which is not an uploaded file.

content_type · string | null · required

The uploaded file’s MIME type.

filename · string | null · required

The uploaded file’s name.

platform · 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.

url · string | null · required

A URL to download the attachment.

evidence_due_at · string | null · required

The deadline to submit evidence, as an ISO 8601 timestamp. Whop reserves the last 24 hours before the processor’s own cutoff to forward the submission.

evidence_editable · boolean · required

Whether evidence can still be changed and submitted.

evidence_locked_reason · string | null · required

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

Available options: submitted, response_window_closed, not_contestable

evidence_submitted_at · string | null · required

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

generated_response_attachment · object | null · required

The AI-generated representment document filed with the processor on the seller’s behalf, once ready. Null until generation completes, and for disputes not using Whop Dispute Fighter.

Properties

id · string | null · required

The attachment’s ID. null for a Whop-hosted policy, which is not an uploaded file.

content_type · string | null · required

The uploaded file’s MIME type.

filename · string | null · required

The uploaded file’s name.

platform · 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.

url · string | null · required

A URL to download the attachment.

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.

issuer_comments · 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

received_at · string | null · required

When the comment was received, as an ISO 8601 timestamp.

text · string · required

What the issuer wrote, as received.

payment · object | null · required

The payment being disputed.

Properties

id · string · required

Payment ID, prefixed pay_.

amount · number | null · required

What the customer was charged, in whole units of the payment’s currency.

card_brand · string | null · required

Card brand, when the customer paid by card.

card_last4 · string | null · required

Last four digits of the card, when the customer paid by card.

created_at · string · required

When the payment was made, as an ISO 8601 timestamp.

currency · 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.

payment_instrument · 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

card · object | null · required

Card payments only: the card’s network and last four.

Properties

brand · string · required

The network identifier (visa, amex, …), matching card.networks entries and saved card payment methods.

last4 · string | null · required

The card’s last four digits, when captured.

display_name · string · required

Buyer-facing instrument name — “Visa •••• 4242” when the card surfaced, else the method’s own name (“Klarna”).

icons · object · required

The standard icon set: square and card shapes, each in light and dark colorways.

Properties

card · object · required

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

Properties

dark · object · required

The colorway for dark surfaces.

Properties

png_1x · string · required

Raster fallback at the shape’s native size.

png_2x · string · required

Raster fallback at double density.

png_4x · string · required

Raster fallback at quadruple density.

svg · string · required

The vector file. Prefer this everywhere SVG renders.

light · object · required

The colorway for light surfaces.

Properties

png_1x · string · required

Raster fallback at the shape’s native size.

png_2x · string · required

Raster fallback at double density.

png_4x · string · required

Raster fallback at quadruple density.

svg · string · required

The vector file. Prefer this everywhere SVG renders.

square · object · required

The square tile (32x32).

Properties

dark · object · required

The colorway for dark surfaces.

Properties

png_1x · string · required

Raster fallback at the shape’s native size.

png_2x · string · required

Raster fallback at double density.

png_4x · string · required

Raster fallback at quadruple density.

svg · string · required

The vector file. Prefer this everywhere SVG renders.

light · object · required

The colorway for light surfaces.

Properties

png_1x · string · required

Raster fallback at the shape’s native size.

png_2x · string · required

Raster fallback at double density.

png_4x · string · required

Raster fallback at quadruple density.

svg · string · required

The vector file. Prefer this everywhere SVG renders.

installment_count · number | null · required

Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.

payment_method_type · string · required

The payment method type identifier, e.g. card, klarna, apple_pay.

payment_method_type · string | null · required

How the customer paid, such as card or paypal.

payment_processor · string | null · required

The processor that handled the payment, such as stripe.

plan_id · string | null · required

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

product_id · string | null · required

The product the disputed payment was for, prefixed prod_.

rapid_dispute_resolution · boolean · required

Whether Visa Rapid Dispute Resolution settled this automatically. These refund the customer without an evidence round.

reason · string · required

Why the customer says they are disputing, normalized across card networks. other covers a code Whop has not categorized yet — read reason_code for the raw value.

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

reason_code · string | null · required

The raw card-network or processor reason code, such as 10.4.

status · 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 closed ended without a ruling. A dispute past its evidence_due_at reports under_review — the window to respond has closed.

Available options: needs_response, under_review, won, lost, closed

updated_at · 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": "[e-mail]",
		"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": "[e-mail]",
		"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",
				"document_type": "product_image",
				"filename": "before-and-after-coating.png",
				"content_type": "image/png",
				"url": "https://cdn.whop.com/attachments/before-and-after-coating.png"
			}
		]
	},
	"evidence_due_at": "2026-06-15T00:00:00Z",
	"evidence_editable": true,
	"evidence_locked_reason": null,
	"evidence_submitted_at": null,
	"generated_response_attachment": null,
	"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": "stripe",
		"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"
			},
			"installment_count": null
		}
	},
	"plan_id": "plan_xxxxxxxxxxxxx",
	"product_id": "prod_xxxxxxxxxxxxx",
	"rapid_dispute_resolution": false,
	"reason": "fraudulent",
	"reason_code": "10.4",
	"status": "needs_response",
	"updated_at": "2026-06-01T12:00:00Z"
}