The Update Dispute API

Single endpoint fits all

PATCH https://api.chargeflow.io/public/{api_version}/disputes/{disputeId}

Use the Update Dispute endpoint to send enrichment data for a dispute in a single call. You can include transaction data, order data, subscription data, and any other relevant signals that improve your chances of winning.

Key ideas

Call PATCH /{api_version}/disputes/{dispute_id} with the Chargeflow dispute ID (dispute.id) to add or update enrichment data.
The endpoint supports upsert semantics: send only the fields you have, and Chargeflow will add or update them.
Arrays are special: when you update an array field, you must pass the complete array contents you want stored. See the array's note below.

Important: arrays and merging behavior

When updating array fields (for example, products, fulfillments), the API treats the passed array as the exact array to be stored. That means:

To add an item, include the existing items and the new item in the payload.
If you omit existing items, they will be removed.
Chargeflow validates objects in arrays and returns clear validation errors if formats are incorrect.

Example: to append a new product, read the current array (or use the dispute.created event), then PATCH with the full array, including the new product.

Current stored value (example)

Before your update, the dispute may already contain one product:

"order": {
  "products": [
    {
      "name": "Shoes",
      "id": "123456789",
      "type": "physical_good",
      "quantity": 1,
      "description": "Nice shoes",
      "price": 150
    }
  ]
}

To append a new product

Read the current array (or use the dispute.created event) and send the full array, including the new item:

{
  "order": {
    "products": [
      {
        "name": "Shoes",
        "id": "123456789",
        "type": "physical_good",
        "quantity": 1,
        "description": "Nice shoes",
        "price": 150
      },
      {
        "name": "Socks",
        "id": "987654321",
        "type": "physical_good",
        "quantity": 2,
        "description": "Comfort socks",
        "price": 20
      }
    ]
  }
}

Note

If you omit the original Shoes item in the payload above, Chargeflow will replace the stored array with only Socks - the Shoes item would be removed.

Example request: inline data creation

Use inline data creation when you need to include the actual data in the same PATCH call rather than linking to existing Chargeflow objects. Common situations:

No existing Chargeflow object: The relevant object does not yet exist in Chargeflow, so you must send the data directly.
Immediate enrichment required: The dispute is urgent, and you need to add evidence in a single step.
External systems can’t provide IDs: Your systems or partners cannot return a Chargeflow object.

Quick recommendation: Prefer linking existing Chargeflow objects when possible to avoid duplication and keep payloads small. Use inline creation when linking is not possible or would delay your response

Example:

{
  "transaction": {
    "payment_method": {
      "checks": {
        "three_d_secure_result": "passed",
        "avs_results": "Y",
        "address_line1_check": "passed",
        "address_zip_check": "passed",
        "cvc_check": "passed"
      },
      "name": "John Doe",
      "type": "card",
      "last4": 4242,
      "expiry_month": "12",
      "expiry_year": "2027",
      "brand": "visa",
      "country": "US"
    },
    "billing_address": {
      "name": "John Doe",
      "line1": "123 Main St",
      "line2": "Apt 4B"",
      "city": "New York",
      "country": "US",
      "state": "NY",
      "zip_code": "10001",
      "phone": "1(123)4567890"
    },
    "source_id": "trx_1234567890",
    "created_at": "2025-01-27T10:00:00Z",
    "type": "paid",
    "amount": 100,
    "currency": "USD"
  }
}

Multiple disputes on the same transaction

A single transaction can generate more than one dispute. To avoid duplication, Chargeflow will attempt to reuse enrichment data from previous disputes involving the same transaction when possible. If automatic reuse is not possible or you prefer explicit linking, pass existing Chargeflow object IDs (for example: transaction, order, or other object IDs) in your PATCH payload to link the objects to the new dispute. This keeps payloads small and ensures consistent data across related disputes.

Example request: link existing objects

If the transaction or order is already stored in Chargeflow, pass the object IDs instead of resending the full payload. This avoids duplication and keeps payloads small.

{
  "transaction": "b6acc3e8408d1d6e78797725",
  "order": "e4d0437fb81cb881cc6bc26a"
}

Chargeflow will link those objects to the dispute and reuse their data for enrichment and generation.

Note

The dispute.created event is triggered after Chargeflow fully ingests and enriches the dispute. Use this event to view which data Chargeflow already has and to focus your enrichment on the missing, high-impact artifacts.

Response: updated dispute returned

When your PATCH request succeeds, Chargeflow returns the updated dispute object in the response. The returned dispute includes the enrichment data you just sent (or linked), so you can confirm the update immediately.

Example (response):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "dis_12345",
  "source_id": "proc_67890",
  "account_id": "act_112233",
  "ext_account_id": "ext_act_445566",
  "created_at": "2025-01-27T10:00:00Z",
  "reason": "fraud",
  "due_by": "2025-02-10T10:00:00Z",
  "source": "stripe",
  "amount": 150,
  "currency": "USD",
  "status": "needs_response",
  "stage": "chargeback",
  "closed_at": null,
  "evidence": {},
  "transaction": {
    "id": "trx_654321",
    "source_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2025-01-26T15:00:00Z",
    "type": "paid",
    "amount": 150,
    "currency": "USD",
    "payment_method": {
      "name": "John Doe",
      "type": "card",
      "last4": 4242,
      "expiry_month": "12",
      "expiry_year": "2027",
      "brand": "visa",
      "country": "US",
      "checks": {
        "three_d_secure_result": "passed",
        "avs_results": "Y",
        "address_line1_check": "passed",
        "address_zip_check": "passed",
        "cvc_check": "passed"
      }
    },
    "billing_address": {
      "name": "John Doe",
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "New York",
      "country": "US",
      "state": "NY",
      "zip_code": "10001",
      "phone": "1(123)4567890"
    }
  },
  "order": {
    "id": "ord_98765",
    "source_id": "748e2a7c-4d21-11ee-8c99-0242ac120002",
    "account_id": "act_112233",
    "ext_account_id": "ext_act_445566",
    "created_at": "2025-01-26T14:30:00Z",
    "payment_status": "paid",
    "name": "#ORD-98765",
    "type": "pre_order",
    "amount": 150,
    "currency": "USD",
    "customer": {
      "name": "John Doe",
      "email": "[email protected]",
      "customer_since": "2023-06-15T12:00:00Z",
      "order_count": 10,
      "phone_number": "1(123)4567890",
      "ip_address": "192.168.1.1",
      "verified_email": true
    },
    "products": [
      {
        "name": "Wireless Headphones",
        "id": "prod_12345",
        "type": "physical_good",
        "quantity": 1,
        "description": "Noise-canceling wireless headphones with Bluetooth connectivity.",
        "image_url": "https://example.com/images/products/12345.jpg",
        "price": 150
      }
    ],
    "shipping_address": {
      "name": "John Doe",
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "New York",
      "country": "US",
      "state": "NY",
      "zip_code": "10001",
      "phone": "1(123)4567890"
    },
    "fulfillments": [
      {
        "product_id": "prod_12345",
        "shipped_at": "2025-01-26T18:00:00Z",
        "shipping_line_title": "FedEx Air Express Shipping",
        "shipping_method_price": 0,
        "tracking_number": "1Z999AA10123456789",
        "courier": "FedEx"
      }
    ]
  },
  "activity_logs": null,
  "customer_communication": "ccm_01j92p1x8a6y7t4gz8d9w3n5qk",
  "booking": null
}

Next Steps

Map your systems to Chargeflow fields and decide which objects you will link vs. send inline.
Subscribe to dispute.createdSo your enrichment flows can trigger automatically