> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargeblast.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fetch Disputes
> Get all the chargeback disputes from your Chargeblast account.
Pass `managedByChargeblast=true` to return only the disputes Chargeblast fights on your behalf. Each dispute carries `disputeStatus` (`needs_response`, `under_review`, `won`, `lost`, ...), `isManagedByChargeblast`, `isSubmittedEvidenceByChargeblast` and `submissionDate`. Fields that do not apply are omitted from the JSON rather than sent as `null`.
This endpoint is enabled per account. Ask your account manager to turn it on for your API key. Use `startDate` / `endDate` (ISO 8601 or `yyyy-MM-dd`) for incremental pulls. `per` defaults to 10 and is capped at 100.
## OpenAPI
````yaml get /api/v2/disputes
openapi: 3.0.1
info:
title: Chargeblast API
version: 0.1.0
servers:
- url: https://api.chargeblast.com
security: []
tags:
- name: Credit Requests
- name: Sync Data
- name: Alerts
- name: Disputes
- name: Enrollment
paths:
/api/v2/disputes:
get:
tags:
- Disputes
summary: Fetch Disputes
description: >-
Get all the chargeback disputes from your Chargeblast account. Each
dispute includes linked alert, deflection, and evidence-submission data
where available — roughly matching what the Chargeblast dashboard shows
for a dispute.
operationId: disputes
parameters:
- name: status
in: query
required: false
description: >-
Filter by dispute status. Possible values: needs_response,
under_review, charge_refunded, won, lost, protected, prevented.
schema:
type: string
nullable: true
enum:
- needs_response
- under_review
- charge_refunded
- won
- lost
- protected
- prevented
- name: startDate
in: query
required: false
description: >-
ISO8601 date (or date-only, e.g. 2026-06-01). Only return disputes
opened on or after this date.
schema:
nullable: true
type: string
- name: endDate
in: query
required: false
description: >-
ISO8601 date (or date-only, e.g. 2026-06-01). Only return disputes
opened on or before this date.
schema:
nullable: true
type: string
- name: managedByChargeblast
in: query
required: false
description: >-
Set to true to return only the disputes Chargeblast manages (the
ones our team fights on your behalf). Omit to include every dispute;
false is rejected.
schema:
type: boolean
nullable: true
- name: page
required: false
in: query
schema:
format: int64
nullable: true
type: integer
description: The starting page of the request. Default value of 1.
- name: per
in: query
required: false
description: >-
How many objects to request per page. Default value of 10, capped at
100.
schema:
format: int64
nullable: true
type: integer
- name: X-API-Key
required: true
in: header
schema:
type: string
description: Your API key. Sent in the `X-API-Key` header.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/APIDisputesResponse'
components:
schemas:
APIDisputesResponse:
type: object
required:
- disputes
- page
- per
- total
properties:
disputes:
type: array
items:
$ref: '#/components/schemas/APIDisputeDetail'
description: The disputes for this page.
page:
type: integer
format: int64
description: The current page.
per:
type: integer
format: int64
description: How many objects are returned per page.
total:
type: integer
format: int64
description: Total number of disputes matching the filter.
APIDisputeDetail:
type: object
required:
- dispute
- alerts
- deflections
- submissions
properties:
dispute:
$ref: '#/components/schemas/CommonDisputeDirectDTO'
description: >-
The chargeback dispute. Recovery outcome fields: `disputeStatus`
(needs_response, under_review, won, lost, ...);
`isManagedByChargeblast`, `isSubmittedEvidenceByChargeblast`,
`isBilled` and `invoicedDate` (omitted until Chargeblast has
enriched the dispute); `submissionDate` (when evidence was
submitted, omitted if it never was). Optional fields without a value
are omitted from the JSON rather than sent as null.
alerts:
type: array
items:
$ref: '#/components/schemas/ExportAlert'
description: >-
Alerts (Ethoca, CDRN, RDR, TC40) linked to the charge behind this
dispute, if any.
deflections:
type: array
items:
$ref: '#/components/schemas/ExportDeflection'
description: >-
Compelling Evidence / Fast Pay Thru deflections linked to the charge
behind this dispute, if any.
submissions:
type: array
items:
$ref: '#/components/schemas/ChargeSubmissionDTO'
description: >-
Evidence submissions filed for this dispute, if any, each with its
evidence documents.
CommonDisputeDirectDTO:
type: object
required:
- transactionDate
- disputeDate
- amount
- source
- chargeId
- brand
- userId
- daysLeftToRespond
- supportsAutoRepresentment
properties:
id:
type: string
nullable: true
description: Chargeblast dispute id.
transactionDate:
type: string
format: date-time
description: Date and time of the original charge.
disputeDate:
type: string
format: date-time
description: Date and time the dispute was opened.
submittedEvidence:
type: boolean
nullable: true
description: Whether evidence has already been submitted for this dispute.
amount:
type: number
format: double
description: Disputed transaction amount, in cents. For example, $19.99 is 1999.
currency:
type: string
nullable: true
description: ISO currency code of the original charge (e.g. USD).
customer:
nullable: true
type: string
refunded:
type: boolean
nullable: true
descriptor:
description: Billing descriptor shown on the card statement.
nullable: true
type: string
status:
allOf:
- $ref: '#/components/schemas/CommonChargeDirectStatus'
nullable: true
description: Status of the original charge.
last4:
nullable: true
type: string
shop:
nullable: true
type: string
bin:
nullable: true
type: string
wallet:
allOf:
- $ref: '#/components/schemas/CommonChargeDirectWallet'
nullable: true
source:
$ref: '#/components/schemas/CommonChargeChargePlatform'
chargeId:
type: string
description: Chargeblast charge id linked to this dispute.
accountId:
nullable: true
type: string
brand:
$ref: '#/components/schemas/CommonChargeDirectBrand'
funding:
allOf:
- $ref: '#/components/schemas/CommonChargeDirectFunding'
nullable: true
createdAt:
format: date-time
type: string
nullable: true
subscriptionId:
nullable: true
type: string
subAccountId:
nullable: true
type: string
disputeStatus:
type: string
nullable: true
enum:
- needs_response
- under_review
- charge_refunded
- won
- lost
- protected
- prevented
description: >-
Current dispute status: needs_response, under_review,
charge_refunded, won, lost, protected, or prevented.
reason:
type: string
nullable: true
description: >-
Issuer dispute reason (e.g. fraudulent, product_not_received,
unrecognized).
isRDR:
type: boolean
nullable: true
description: Whether the dispute was deflected via RDR.
riskScore:
type: number
nullable: true
format: double
userId:
type: string
description: Chargeblast company id that owns this dispute.
issuer:
nullable: true
type: string
amountUSD:
type: number
format: double
nullable: true
description: Disputed amount converted to USD cents.
customerEmail:
nullable: true
type: string
authorizationCode:
nullable: true
type: string
streamId:
nullable: true
type: string
arn:
type: string
nullable: true
description: Acquirer Reference Number of the original charge.
is3DS:
type: boolean
nullable: true
expirationDate:
type: string
format: date-time
nullable: true
description: Deadline to respond to the dispute, when the processor supplies one.
kind:
allOf:
- $ref: '#/components/schemas/CommonDisputeDirectKind'
nullable: true
daysLeftToRespond:
type: string
description: >-
Human-readable time remaining to respond, e.g. `12 days` or `Expires
soon`.
explanation:
allOf:
- $ref: '#/components/schemas/DisputeExplanation'
nullable: true
supportsAutoRepresentment:
type: boolean
alertId:
type: string
nullable: true
description: Linked alert id when Chargeblast has enriched this dispute.
externalUrl:
nullable: true
type: string
winLikelihood:
allOf:
- $ref: '#/components/schemas/DisputeWinLikelihoodDTO'
nullable: true
isBilled:
type: boolean
nullable: true
description: >-
Whether Chargeblast has billed this recovery. Omitted until the
dispute is enriched.
invoicedDate:
type: string
format: date-time
nullable: true
description: >-
When Chargeblast invoiced this recovery. Omitted until the dispute
is enriched.
submissionDate:
type: string
format: date-time
nullable: true
description: >-
When evidence was submitted. Omitted if evidence was never
submitted.
isManagedByChargeblast:
type: boolean
nullable: true
description: >-
Whether Chargeblast is fighting this dispute on your behalf. Omitted
until the dispute is enriched.
isSubmittedEvidenceByChargeblast:
type: boolean
nullable: true
description: >-
Whether Chargeblast submitted evidence for this dispute. Omitted
until the dispute is enriched.
ExportAlert:
properties:
provider:
type: string
nullable: true
description: 'Provider associated with the alert. Possible values: ethoca, verifi'
id:
type: string
description: Id for the alert.
card:
description: The redacted card number, e.g., 424242****1234.
type: string
nullable: true
issuer:
type: string
description: Issuer of the card (e.g., bank or financial institution).
nullable: true
invoicedAt:
description: Date and time when the alert was invoiced.
format: date-time
nullable: true
type: string
authCode:
description: Authorization code for the transaction, if available.
type: string
nullable: true
site:
description: Merchant's website or site string associated with the alert.
type: string
nullable: true
customerEmail:
nullable: true
type: string
description: Customer's email address associated with the alert, if available.
creditStatus:
type: string
nullable: true
description: Status of the credit (if any) associated with the alert.
alertType:
description: Type of alert, e.g., FRAUD, DISPUTE.
type: string
creditAppealed:
type: boolean
description: Indicates if the credit associated with the alert was appealed.
currency:
nullable: true
type: string
description: Currency code in ISO format (e.g., USD, EUR) for the transaction.
reasonCode:
nullable: true
description: >-
Reason code associated with the alert, often indicating the nature
of the dispute.
type: string
createdAt:
description: Date and time when the alert was created.
type: string
format: date-time
merchantId:
description: Identifier for the merchant within the system.
type: string
nullable: true
acquirerAction:
nullable: true
type: string
description: >-
Actions taken by the acquirer in response to the alert. Only
relevant for RDR and other acquirer side alerts - either Resolved or
Declined.
alertId:
description: >-
Unique identifier for the alert within the provider's system. Will
match the id field.
nullable: true
type: string
amount:
type: number
description: >-
Transaction amount for the alert. $139.38 will be represented as
139.38
format: double
resolvedDate:
description: Date and time when the alert was resolved.
format: date-time
nullable: true
type: string
resolvedByApi:
description: Indicates if the alert was resolved via API.
nullable: true
type: boolean
externalOrder:
description: External charge id related to the alert.
nullable: true
type: string
externalUrl:
nullable: true
type: string
description: URL linking to an external reference for the alert.
creditNotes:
type: string
description: Additional notes or information regarding the credit status.
nullable: true
arn:
description: Acquirer Reference Number, unique identifier for the transaction.
nullable: true
type: string
attributes:
type: object
nullable: true
additionalProperties:
type: string
description: >-
Optional string key-value metadata associated with the alert.
Included on webhook payloads and when fetching alerts via the API
when present.
example:
order_number: '#1533'
processor_id: proc_b381c83a9bc8a93
transactionDate:
type: string
description: Date and time when the transaction took place.
format: date-time
customerId:
description: >-
Unique identifier for the customer associated with the alert, if
available.
nullable: true
type: string
descriptor:
description: Billing descriptor shown on the card statement.
nullable: true
type: string
subprovider:
description: Specific sub-provider within the provider service.
type: string
cardBrand:
type: string
description: The card network (e.g., Visa, Mastercard, Amex).
nullable: true
responseAction:
description: Response action taken in response to the alert.
nullable: true
type: string
type: object
description: Export alert details.
required:
- alertType
- amount
- createdAt
- creditAppealed
- id
- subprovider
- transactionDate
ExportDeflection:
type: object
required:
- chargeId
- type
- network
- status
- amount_usd
- currency
- deflectionDate
properties:
chargeId:
type: string
type:
type: string
description: >-
Deflection type: `CE` (Compelling Evidence) or `FPT` (Fast Pay
Thru).
network:
type: string
description: '`OI` (Order Insights) or `CC` (Consumer Clarity).'
status:
type: string
amount_usd:
type: number
format: double
description: Deflected amount in USD cents.
currency:
type: string
deflectionDate:
type: string
format: date-time
ChargeSubmissionDTO:
type: object
required:
- isBilled
- isManual
- evidence
properties:
id:
nullable: true
type: string
isBilled:
type: boolean
isManual:
type: boolean
createdAt:
format: date-time
type: string
nullable: true
disputeEnrichedId:
nullable: true
type: string
commonDisputeDirectId:
nullable: true
type: string
evidence:
type: array
items:
$ref: '#/components/schemas/ChargeSubmissionEvidenceDTO'
CommonChargeDirectStatus:
type: string
enum:
- succeeded
- failed
- pending
CommonChargeDirectWallet:
type: string
enum:
- apple_pay
- paypal
- google_pay
- link
- ''
- Bank
- cash_app
- pulse
- star
- nyce
- accel
- shazam
- pix
- klarna
- affirm
- afterpay_clearpay
- zip
- amazon_pay
- sepa_debit
- sunbit
CommonChargeChargePlatform:
type: string
enum:
- Stripe
- Shopify
- CheckoutChamp
- Braintree
- Mamopay
- Maverick
- Sticky
- Unknown
- API
- 29Next
- Square
- Spreedly
- Airwallex
- NMI
- Auth
- Primer
- Payarc
- PaymentKit
- Chargebee
- Phoenix
- Adyen
- Recurly
- Gr4vy
- Recharge
- Openpay
- Finix
- Worldpay
- FMJ
- Coinflow
- Xecom
- Vrio
- Checkout
- a55
- Seal
- GuestyPay
- Fyntek
- Paytech
- SwissCRM
- Paysight
- Whop
- Spark
- Kurv
- Everflow
- IMerchant
- RocketGate
description: |-
• Stripe → Stripe
• Shopify → Shopify
• CheckoutChamp → CheckoutChamp
• Braintree → Braintree
• Mamopay → Mamopay
• Maverick → Maverick
• Sticky → Sticky
• Unknown → Unknown
• API → API
• 29Next → Next
• Square → Square
• Spreedly → Spreedly
• Airwallex → Airwallex
• NMI → NMI
• Auth → Auth
• Primer → Primer
• Payarc → Payarc
• PaymentKit → PaymentKit
• Chargebee → Chargebee
• Phoenix → Phoenix
• Adyen → Adyen
• Recurly → Recurly
• Gr4vy → Gr4vy
• Recharge → Recharge
• Openpay → Openpay
• Finix → Finix
• Worldpay → Worldpay
• FMJ → FMJ
• Coinflow → Coinflow
• Xecom → Xecom
• Vrio → Vrio
• Checkout → Checkout
• a55 → a55
• Seal → Seal
• GuestyPay → GuestyPay
• Fyntek → Fyntek
• Paytech → Paytech
• SwissCRM → SwissCRM
• Paysight → Paysight
• Whop → Whop
• Spark → Spark
• Kurv → Kurv
• Everflow → Everflow
• IMerchant → IMerchant
• RocketGate → RocketGate
CommonChargeDirectBrand:
type: string
enum:
- mastercard
- visa
- amex
- discover
- unknown
- ''
CommonChargeDirectFunding:
type: string
enum:
- credit
- debit
- prepaid
- ''
CommonDisputeDirectKind:
type: string
enum:
- chargeback
- inquiry
- pre_arbitration
- second_chargeback
DisputeExplanation:
type: string
enum:
- alert_not_handled
- alerted_refunded_late
- alerted_bank_violated_sop
- alert_safe_failed
- alert_rejected
- alert_unknown
- rdr_deflected
- out_of_coverage
- alert_marked_as_already_refunded
- descriptor_not_enrolled
- descriptor_enrolled_out_of_coverage
- dispute_on_debit_network
- no_arn
- alert_update_request_failed
- unknown
DisputeWinLikelihoodDTO:
type: object
required:
- score
- computedAt
- modelVersion
- source
properties:
score:
type: number
format: double
description: Probability that the merchant wins the dispute, from 0 to 1.
computedAt:
type: string
format: date-time
modelVersion:
type: string
source:
type: string
ChargeSubmissionEvidenceDTO:
type: object
required:
- isSubmittedToProcessor
- url
properties:
id:
nullable: true
type: string
isSubmittedToProcessor:
type: boolean
url:
type: string
createdAt:
format: date-time
type: string
nullable: true
submittedByAccountId:
nullable: true
type: string
````