Disputes

Update Dispute

Updates the evidence on a dispute, and optionally submits it to the card network.

Saves the provided evidence fields, leaving any omitted fields unchanged; a file field sent as "" is cleared. File fields reference Flex file IDs that must have purpose dispute_evidence; they are resolved to the underlying card-network files before submission. When submit is true, the evidence is finalized and submitted to the network to contest the dispute — evidence cannot be edited after submission.

The dispute must be in a needs_response or warning_needs_response status.

post/v1/disputes/{dispute_id}

Request

Base URL
https://api.withflex.com
URL
https://api.withflex.com/v1/disputes/{dispute_id}
Auth
HTTP bearer

Path parameters

dispute_idstring required

Example:fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA

Request body

Example request

{
  "dispute": {
    "evidence": {
      "access_activity_log": "example_value",
      "billing_address": "123 Main St",
      "cancellation_policy": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "cancellation_policy_disclosure": "example_value",
      "cancellation_rebuttal": "example_value",
      "customer_communication": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "customer_email_address": "john.doe@example.com",
      "customer_name": "Example",
      "customer_purchase_ip": "example_value",
      "customer_signature": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "duplicate_charge_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "duplicate_charge_explanation": "example_value",
      "duplicate_charge_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "product_description": "Premium SPF 50 mineral sunscreen",
      "receipt": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "refund_policy": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "refund_policy_disclosure": "example_value",
      "refund_refusal_explanation": "example_value",
      "service_date": "example_value",
      "service_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "shipping_address": "123 Main St",
      "shipping_carrier": "example_value",
      "shipping_date": "example_value",
      "shipping_documentation": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "shipping_tracking_number": "example_value",
      "uncategorized_file": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "uncategorized_text": "example_value"
    },
    "submit": false
  }
}

Response

An envelope wrapping a single dispute object.

Example response

{
  "dispute": {
    "dispute_id": "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "payment_intent_id": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "amount": 2500,
    "currency": "usd",
    "charge_id": "fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "metadata": {
      "order_id": "8842",
      "channel": "shopify"
    },
    "created_at": "2026-06-15T14:30:00Z",
    "status": "lost",
    "reason": "bank_cannot_process",
    "is_charge_refundable": false,
    "evidence": {
      "access_activity_log": "string",
      "customer_name": "string",
      "customer_email_address": "string",
      "customer_purchase_ip": "string",
      "billing_address": "string",
      "shipping_address": "string",
      "shipping_tracking_number": "string",
      "shipping_carrier": "string",
      "shipping_date": "string",
      "service_date": "string",
      "product_description": "string",
      "refund_policy_disclosure": "string",
      "refund_refusal_explanation": "string",
      "cancellation_policy_disclosure": "string",
      "cancellation_rebuttal": "string",
      "duplicate_charge_explanation": "string",
      "duplicate_charge_id": "string",
      "uncategorized_text": "string",
      "customer_communication": {
        "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "filename": "string",
        "stripe_file_id": "string"
      },
      "customer_signature": {
        "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "filename": "string",
        "stripe_file_id": "string"
      },
      "shipping_documentation": {
        "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "filename": "string",
        "stripe_file_id": "string"
      },
      "receipt": {
        "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "filename": "string",
        "stripe_file_id": "string"
      },
      "duplicate_charge_documentation": {
        "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "filename": "string",
        "stripe_file_id": "string"
      },
      "service_documentation": {
        "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "filename": "string",
        "stripe_file_id": "string"
      },
      "uncategorized_file": {
        "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "filename": "string",
        "stripe_file_id": "string"
      },
      "cancellation_policy": {
        "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "filename": "string",
        "stripe_file_id": "string"
      },
      "refund_policy": {
        "file_id": "ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "filename": "string",
        "stripe_file_id": "string"
      }
    },
    "evidence_details": {
      "due_by": "2026-06-15T14:30:00Z",
      "has_evidence": false,
      "past_due": false,
      "submission_count": 3
    },
    "balance_transactions": [
      {
        "balance_transaction_id": "fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
        "amount": 2500,
        "fee": 2500,
        "net": 2500,
        "status": "available",
        "type": "string",
        "reporting_category": "example_value",
        "category": "example_value",
        "created_at": "2026-06-15T14:30:00Z"
      }
    ],
    "payment_method_details": {
      "type": "string",
      "card": {
        "brand": "visa",
        "network_reason_code": "example_value"
      }
    },
    "test_mode": false,
    "client_reference_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA"
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.