Stripe: Submit a dispute

← Issuing operations · Get started

Operation stripe.postissuingdisputesdisputesubmit

Provider route: POST /v1/issuing/disputes/{dispute}/submit. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["issuing"]["postIssuingDisputesDisputeSubmit"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.issuing.postIssuingDisputesDisputeSubmit(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.issuing.post_issuing_disputes_dispute_submit(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.dispute	string	Required within parent	Maximum length: 5000
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	Model	Optional	Expand Update a payout — request body — body

Referenced models: Update a payout — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a dispute — response body

Referenced models: Create a dispute — response body

Schemas

705 more schemas are linked from the tables above, on the schema pages.

Create a dispute — response body

Field	Type	Presence	Description and constraints
$	object	Root	As a [card issuer](https://docs.stripe.com/issuing), you can dispute transactions that the cardholder does not recognize, suspects to be fraudulent, or has other issues with. Related guide: [Issuing disputes](https://docs.stripe.com/issuing/purchases/disputes)
amount	JSON	Required within parent
amount (anyOf 1)	integer	Alternative	Disputed amount in the card's currency and in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal). Usually the amount of the `transaction`, but can differ (usually because of currency fluctuation).
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
balance_transactions	JSON	Optional
balance_transactions (anyOf 1)	array	Alternative	List of balance transactions associated with the dispute.
balance_transactions (anyOf 1)[]	Model	Each item	Expand Retrieve a balance transaction — balance get Balance History Id — response body
balance_transactions (anyOf 2)	null	Alternative
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Required within parent	The currency the `transaction` was made in. Format: currency
evidence	Model	Required within parent	Expand Create a dispute — response body — evidence
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
loss_reason	string	Optional	The enum that describes the dispute loss outcome. If the dispute is not lost, this field will be absent. New enum values may be added in the future, so be sure to handle unknown values. Known values: cardholder_authentication_issuer_liability, eci5_token_transaction_with_tavv, excess_disputes_in_timeframe, has_not_met_the_minimum_dispute_amount_requirements, invalid_duplicate_dispute, invalid_incorrect_amount_dispute, invalid_no_authorization, invalid_use_of_disputes, merchandise_delivered_or_shipped, merchandise_or_service_as_described, not_cancelled, other, refund_issued, submitted_beyond_allowable_time_limit, transaction_3ds_required, transaction_approved_after_prior_fraud_dispute, transaction_authorized, transaction_electronically_read, transaction_qualifies_for_visa_easy_payment_service, transaction_unattended
metadata	object	Required within parent	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field
metadata.*	string	Additional keys	Maximum length: 500
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: issuing.dispute
status	string	Required within parent	Current status of the dispute. Known values: expired, lost, submitted, unsubmitted, won
transaction	JSON	Required within parent	The transaction being disputed.
transaction (anyOf 1)	string	Alternative	Maximum length: 5000
transaction (anyOf 2)	Model	Alternative	Expand Update a transaction — response body
treasury	JSON	Optional
treasury (anyOf 1)	JSON	Alternative	[Treasury](https://docs.stripe.com/api/treasury) details related to this dispute if it was created on a [FinancialAccount](https://docs.stripe.com/api/treasury/financial_accounts)
treasury (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a dispute — response body — treasury value debit reversal, received debit
treasury (anyOf 2)	null	Alternative

Referenced models: Retrieve a balance transaction — balance get Balance History Id — response body, Update a transaction — response body, Create a dispute — response body — evidence, Create a dispute — response body — treasury value debit reversal, received debit

Update a payout — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
expand	array	Optional	Specifies which fields in the response should be expanded.
expand[]	string	Each item	Maximum length: 5000
metadata	JSON	Optional	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
metadata (anyOf 1).*	string	Additional keys
metadata (anyOf 2)	string	Alternative	One of:

Create a dispute — response body — evidence

Field	Type	Presence	Description and constraints
$	object	Root
canceled	Model	Optional	Expand Create a dispute — response body — evidence canceled
duplicate	Model	Optional	Expand Create a dispute — response body — evidence duplicate
fraudulent	Model	Optional	Expand Create a dispute — response body — evidence fraudulent
merchandise_not_as_described	Model	Optional	Expand Create a dispute — response body — evidence merchandise not as described
no_valid_authorization	Model	Optional	Expand Create a dispute — response body — evidence fraudulent
not_received	Model	Optional	Expand Create a dispute — response body — evidence not received
other	Model	Optional	Expand Create a dispute — response body — evidence other
reason	string	Required within parent	The reason for filing the dispute. Its value will match the field containing the evidence. Known values: canceled, duplicate, fraudulent, merchandise_not_as_described, no_valid_authorization, not_received, other, service_not_as_described
service_not_as_described	Model	Optional	Expand Create a dispute — response body — evidence service not as described

Referenced models: Create a dispute — response body — evidence canceled, Create a dispute — response body — evidence duplicate, Create a dispute — response body — evidence fraudulent, Create a dispute — response body — evidence merchandise not as described, Create a dispute — response body — evidence not received, Create a dispute — response body — evidence other, Create a dispute — response body — evidence service not as described

Create a dispute — response body — treasury value debit reversal, received debit

Field	Type	Presence	Description and constraints
$	object	Root
debit_reversal	JSON	Optional
debit_reversal (anyOf 1)	string	Alternative	The Treasury [DebitReversal](https://docs.stripe.com/api/treasury/debit_reversals) representing this Issuing dispute Maximum length: 5000
debit_reversal (anyOf 2)	null	Alternative
received_debit	string	Required within parent	The Treasury [ReceivedDebit](https://docs.stripe.com/api/treasury/received_debits) that is being disputed. Maximum length: 5000

Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: connect collection transfer

Field	Type	Presence	Description and constraints
$	object	Root
amount	JSON	Required within parent
amount (anyOf 1)	integer	Alternative	Amount transferred, in cents (or local equivalent).
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
destination	JSON	Required within parent	ID of the account that funds are being collected for.
destination (anyOf 1)	string	Alternative	Maximum length: 5000
destination (anyOf 2)	Model	Alternative	Expand Create an account — response body
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: connect_collection_transfer

Referenced models: Create an account — response body

Policy, approvals and errors

SDK function policy ID: stripe.postissuingdisputesdisputesubmit. Catalog operation: PostIssuingDisputesDisputeSubmit. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source