# Industry Enrichment (https://docs.chargeflow.io/docs/merchants/automation/enrich-a-dispute/by-industry)



<ComingSoon href="/docs/merchants/automation/enrich-a-dispute">
  Industry Enrichment via the `universal_order` field is an upcoming addition to the Enrich Dispute
  API. The endpoints and schemas described here are not yet in the API reference. This section
  documents the model ahead of release so you can plan your integration. To enrich disputes today,
  use the current Enrich a Dispute guide, which covers the live `order` and `transaction` payloads.
</ComingSoon>

`PATCH /public/2025-04-01/disputes/{disputeId}`

You are a merchant enriching a dispute for your industry. Every dispute is a story: the cardholder tells theirs to the issuer, and your job is to give Chargeflow the data to tell yours. Send all your evidence in one `universal_order` block matched to your vertical, and Chargeflow builds reason-code-aware evidence automatically. No explicit type declaration is needed, just include the right block.

<Callout type="info" title="Recommended: Industry Enrichment">
  Industry Enrichment via `universal_order` is the most up-to-date way to enrich disputes. It builds
  reason-code-aware narratives from a single payload tailored to your vertical. Find yours in
  [Choose your block](#choose-your-block).
</Callout>

## How enrichment works [#how-enrichment-works]

1. **Your API call** - send a `PATCH` with `universal_order` containing your order data and the relevant industry block.
2. **Field analysis** - Chargeflow reads the industry fields and identifies the commercial story.
3. **Evidence builder** - Chargeflow crafts a narrative from your data, optimized for the dispute's reason code.
4. **Submission** - the completed evidence package is submitted to the issuer on your behalf.

## Quick start [#quick-start]

Enrich an accommodation dispute in under five minutes. Swap the `accommodation` block for your industry's block (see [Choose your block](#choose-your-block)), keeping `customer` and `order` as the anchors.

```bash title="Terminal"
curl -X PATCH https://api.chargeflow.io/public/2025-04-01/disputes/dp_01HXYZ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "universal_order": {
      "customer": {
        "email": "sarah.chen@example.com",
        "name": "Sarah Chen"
      },
      "order": {
        "external_id": "BK-20260315-8842",
        "currency": "USD",
        "amount": 847.50,
        "ordered_at": "2026-02-10T14:23:00Z",
        "status": "completed"
      },
      "accommodation": {
        "property_name": "The Oceanview Hotel",
        "property_type": "hotel",
        "booked_check_in": "2026-03-15",
        "booked_check_out": "2026-03-18",
        "actual_check_in": "2026-03-15T16:02:00Z"
      }
    }
  }'
```

Once the request succeeds, Chargeflow detects the industry from the block, analyzes the fields against the reason code, builds a tailored narrative, and submits it to the issuer.

<Callout type="idea" title="Re-enrichment">
  Disputes are re-enrichable by design. Call the endpoint again with new evidence whenever you have
  it. Chargeflow uses upsert semantics: send only the fields you have and they are added or updated.
</Callout>

<Callout type="warn" title="`order` vs `universal_order`">
  These fields are mutually exclusive. A request with both returns a `400`. The `transaction` field
  can be sent alongside `universal_order` without issue. See [Error responses](#error-responses).
</Callout>

## Universal fields [#universal-fields]

Every `universal_order` payload shares the same outer envelope. The industry block (`accommodation`, `flight`, `dining`, etc.) tells Chargeflow the commercial story; the envelope carries the cross-industry data. You never specify the type explicitly.

<Callout title="Everything is optional">
  Send whatever data you have. No required fields. Chargeflow builds the best narrative from
  whatever you provide.
</Callout>

| Field          | Type   | How Chargeflow uses it                                                                                                                                            |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customer`     | object | Cardholder identity: `email`, `name`, `phone`, `customer_since`. Long tenure undermines "I never signed up"; a matching name ties the order to the card.          |
| `order`        | object | The commercial story: `external_id`, `amount`, `currency`, `ordered_at`, `status`, `confirmation_code`, `ip_address`.                                             |
| `charges[]`    | array  | Itemized breakdown: `charge_type` (`tax`, `fee`, `tip`, `deposit`, `discount`, `credit`), `amount`, `description`.                                                |
| `policies[]`   | array  | Consent records: `policy_type`, `consented_at`, `policy_url`, `acceptance_method`.                                                                                |
| `activities[]` | array  | Event log of `event_name` + `event_at` pairs (snake\_case names like `booking_confirmed`, `check_in`, `login`). A timestamped audit trail of customer engagement. |
| `addresses[]`  | array  | Named by `kind`: `billing`, `shipping`, `property`, `venue`, `pickup`, `dropoff`, `provider`, `other`. Supports `latitude`/`longitude` for GPS precision.         |
| `refunds[]`    | array  | Refund records: `reason`, `amount`, `refunded_at`, `refund_method`.                                                                                               |

The `order` object also supports confirmation fields that strengthen evidence:

| Field                  | Type      | Purpose                                                          |
| ---------------------- | --------- | ---------------------------------------------------------------- |
| `confirmation_code`    | string    | The booking or order reference the customer received.            |
| `confirmation_methods` | array     | How confirmation was sent, e.g. `["email"]`, `["email", "sms"]`. |
| `confirmation_sent_to` | string    | The email or phone the confirmation was delivered to.            |
| `confirmation_sent_at` | timestamp | When the confirmation was dispatched.                            |

### Recommended data points [#recommended-data-points]

A few data points help win most dispute reasons across every industry:

1. **Customer identity** - `name` and `email` show you hold accurate records of your customers.
2. **Addresses** - `ip_address`, shipping, and billing addresses prove delivery, verify billing/shipping match, and confirm the buyer's location.
3. **Order and product information** - descriptions, prices, discounts, refunds, and images show the customer had clear information about the purchase.

## Choose your block [#choose-your-block]

Search your industry or pick a card. Each block opens with what it covers, the fields that win disputes, and a full payload you can copy. If your platform spans several domains, send the block that matches the specific transaction being disputed: an OTA uses Accommodation for hotel bookings and Flights for air tickets, from the same platform.

<IndustryPicker>
  <IndustryBlock id="accommodation" title="Accommodation" summary="Paying to occupy a space for a defined period." keywords="accommodation hotels resorts vacation rentals airbnb vrbo hostels b&b bed and breakfast serviced apartments campgrounds glamping timeshare lodging ota travel booking check-in">
    **When to use:** a customer pays to occupy a physical space for a defined period. &#x2A;*Industries:** hotels & resorts, vacation rentals, hostels, serviced apartments, bed & breakfasts, campgrounds & glamping, timeshare resorts.

    **Highest-impact:** `actual_check_in` plus cancellation `policies[].consented_at` resolve the vast majority of accommodation disputes. If no cancellation request appears in `activities[]`, that absence is itself evidence.

    ```json title="Accommodation payload"
    {
      "universal_order": {
        "customer": {
          "name": "Sarah Chen",
          "email": "sarah.chen@example.com",
          "customer_since": "2023-06-01"
        },
        "order": {
          "external_id": "BK-20260315-8842",
          "amount": 847.5,
          "currency": "USD",
          "ordered_at": "2026-02-10T14:23:00Z",
          "status": "completed",
          "confirmation_code": "OVH-8842",
          "confirmation_methods": ["email"],
          "confirmation_sent_to": "sarah.chen@example.com",
          "confirmation_sent_at": "2026-02-10T14:23:05Z"
        },
        "accommodation": {
          "property_name": "The Oceanview Hotel",
          "property_type": "hotel",
          "room_type": "King Ocean View",
          "booked_check_in": "2026-03-15",
          "booked_check_out": "2026-03-18",
          "actual_check_in": "2026-03-15T16:02:00Z",
          "actual_check_out": "2026-03-18T10:41:00Z",
          "number_of_nights": 3,
          "guest_name": "Sarah Chen",
          "guests_count": 2,
          "rate_per_night": 265.0,
          "total_accommodation_cost": 795.0,
          "is_no_show": false
        },
        "policies": [
          {
            "policy_type": "cancellation",
            "consented_at": "2026-02-10T14:23:00Z",
            "policy_url": "https://oceanview.example.com/cancellation",
            "acceptance_method": "checkbox"
          }
        ],
        "activities": [
          {
            "event_name": "booking_confirmed",
            "event_at": "2026-02-10T14:23:05Z"
          },
          { "event_name": "check_in", "event_at": "2026-03-15T16:02:00Z" },
          { "event_name": "check_out", "event_at": "2026-03-18T10:41:00Z" }
        ]
      }
    }
    ```

    **Other values:** `property_type` also takes `vacation_rental`, `hostel`, `b_and_b`, and the other property kinds. Cancellation and refund terms live in `policies[]`.
  </IndustryBlock>

  <IndustryBlock id="flights" title="Flights" summary="Scheduled air transportation between two points." keywords="flights airlines commercial charter private aviation helicopter tours air ambulance scenic flights ota travel tickets pnr boarding">
    **When to use:** a customer pays for scheduled air transportation between two points. &#x2A;*Industries:** commercial airlines, charter flights, private aviation, helicopter tours, air ambulance, scenic flights.

    **Highest-impact:** `boarded_at`, `ticket_number`, and `actual_departure` are the core trio - a boarding timestamp with a ticket number and actual departure is nearly irrefutable. `actual_departure`/`actual_arrival` also defeat "flight was canceled" claims.

    ```json title="Flight payload"
    {
      "universal_order": {
        "customer": { "name": "Daniel Moore", "email": "d.moore@example.com" },
        "order": {
          "external_id": "PNR-4KX9QT",
          "amount": 612.3,
          "currency": "USD",
          "ordered_at": "2026-01-22T09:12:00Z",
          "status": "completed",
          "confirmation_code": "4KX9QT",
          "confirmation_methods": ["email", "sms"]
        },
        "flight": {
          "airline_name": "Northwind Air",
          "airline_code": "NWA",
          "flight_number": "NW412",
          "ticket_number": "0142398871234",
          "departure_airport": "KJFK",
          "arrival_airport": "KSFO",
          "booked_departure": "2026-02-14T07:40:00Z",
          "booked_arrival": "2026-02-14T14:05:00Z",
          "actual_departure": "2026-02-14T07:56:00Z",
          "actual_arrival": "2026-02-14T14:12:00Z",
          "passenger_name": "Daniel Moore",
          "cabin_class": "economy",
          "seat_number": "22A",
          "fare_amount": 612.3,
          "checked_bags_count": 1,
          "is_checked_in": true,
          "boarded_at": "2026-02-14T07:21:00Z",
          "is_no_show": false
        },
        "activities": [
          {
            "event_name": "online_check_in",
            "event_at": "2026-02-13T08:02:00Z"
          },
          {
            "event_name": "boarding_pass_scanned",
            "event_at": "2026-02-14T07:21:00Z"
          }
        ]
      }
    }
    ```

    **Other values:** `cabin_class` also takes `premium_economy`, `business`, `first`, `other`. `airline_code` is the 3-char ICAO code, the airports the 4-char one.
  </IndustryBlock>

  <IndustryBlock id="dining" title="Dining" summary="Food or drink prepared and served, on-premise or delivered." keywords="dining restaurants cloud kitchens ghost kitchens catering food delivery meal kit subscriptions wine spirits clubs bars lounges cafe food truck reservation">
    **When to use:** a customer pays for food or beverages prepared and served, on-premise or delivered. &#x2A;*Industries:** restaurants, cloud kitchens, catering, food delivery platforms, meal kit subscriptions, wine & spirits clubs, bars & lounges.

    **Highest-impact:** `reservation_at`, `guest_name`, and a `tip` in `charges[]` - a customer-added gratuity strongly implies voluntary engagement and customers who tip then dispute rarely win.

    ```json title="Dining payload"
    {
      "universal_order": {
        "customer": { "name": "Maya Ortiz", "email": "maya.ortiz@example.com" },
        "order": {
          "external_id": "RSV-77213",
          "amount": 214.8,
          "currency": "USD",
          "ordered_at": "2026-03-02T21:44:00Z",
          "status": "completed"
        },
        "dining": {
          "venue_name": "Trattoria Nove",
          "venue_type": "restaurant",
          "reservation_at": "2026-03-02T19:30:00Z",
          "guests_count": 4,
          "guest_name": "Maya Ortiz",
          "meal_type": "dinner",
          "total_dining_cost": 178.0,
          "price_per_guest": 44.5,
          "is_no_show": false
        },
        "charges": [
          {
            "charge_type": "tip",
            "amount": 32.0,
            "description": "Table gratuity"
          },
          { "charge_type": "tax", "amount": 4.8, "description": "Sales tax" }
        ],
        "activities": [
          {
            "event_name": "reservation_confirmed",
            "event_at": "2026-02-27T10:15:00Z"
          },
          { "event_name": "table_seated", "event_at": "2026-03-02T19:34:00Z" }
        ]
      }
    }
    ```

    **Other values:** `venue_type` also takes `bar`, `cafe`, `catering`, `food_truck`, `other`. `meal_type` takes `breakfast`, `brunch`, `lunch`, `afternoon_tea`, `dinner`, `drinks`, `tasting_menu`, `other`. Gratuity goes in `charges[]` (`charge_type: tip`), delivery fees too (`charge_type: fee`).
  </IndustryBlock>

  <IndustryBlock id="e-commerce" title="E-commerce" summary="A physical product shipped to an address." keywords="e-commerce ecommerce online retail marketplace sellers subscription boxes print on demand wholesale b2b dropshipping shipping tracking fulfillment meal kit">
    **When to use:** a customer pays for a physical product shipped to an address. &#x2A;*Industries:** online retail, marketplace sellers, subscription boxes, print-on-demand, wholesale & B2B, dropshipping.

    **Highest-impact:** `items[].tracking_number` is the most powerful field - Chargeflow automatically fetches carrier data, delivery status, and proof of delivery (no manual tracking events needed). A delivered status with a matching billing/shipping address is near-irrefutable for "item not received".

    ```json title="E-commerce payload"
    {
      "universal_order": {
        "customer": {
          "name": "Priya Raman",
          "email": "priya.raman@example.com",
          "customer_since": "2022-11-04"
        },
        "order": {
          "external_id": "ORD-58412",
          "amount": 236.4,
          "currency": "USD",
          "ordered_at": "2026-04-02T17:08:00Z",
          "status": "completed",
          "ip_address": "203.0.113.42"
        },
        "items": [
          {
            "type": "physical_good",
            "name": "Trailhead Jacket",
            "sku": "TH-JKT-M-OLV",
            "quantity": 1,
            "unit_price": 189.0,
            "total_price": 189.0,
            "url": "https://shop.example.com/products/trailhead-jacket",
            "image_url": "https://cdn.example.com/trailhead-jacket.jpg",
            "tracking_number": "1Z999AA10123456784"
          }
        ],
        "addresses": [
          {
            "kind": "shipping",
            "line1": "418 Maple Street",
            "city": "Austin",
            "postal_code": "78701",
            "country": "US"
          },
          {
            "kind": "billing",
            "line1": "418 Maple Street",
            "city": "Austin",
            "postal_code": "78701",
            "country": "US"
          }
        ]
      }
    }
    ```

    **Other values:** `items[].type` also takes `digital_good`, `food_delivery`, `grocery`, `other`. Send both `addresses[]` kinds and the `ip_address` so billing, shipping, and buyer location line up.
  </IndustryBlock>

  <IndustryBlock id="digital-goods" title="Digital goods" summary="A non-physical product delivered electronically." keywords="digital goods online courses e-learning software licenses digital art nfts ebooks audiobooks stock photos media in-app purchases gaming credits digital subscriptions downloads">
    **When to use:** a customer pays for a non-physical product delivered electronically. &#x2A;*Industries:** online courses, software licenses, digital art & NFTs, e-books & audiobooks, stock photos & media, in-app purchases, gaming credits, digital subscriptions.

    **Highest-impact:** `access_granted_at` and `download_url` prove delivery. Combined with `activities[]` showing use (content\_accessed, lessons completed, files downloaded), the line between "delivered" and "used" becomes your biggest weapon.

    ```json title="Digital goods payload"
    {
      "universal_order": {
        "customer": {
          "name": "Tomás Alvarez",
          "email": "tomas@example.com",
          "customer_since": "2025-09-19"
        },
        "order": {
          "external_id": "LIC-2026-0417",
          "amount": 149.0,
          "currency": "USD",
          "ordered_at": "2026-04-17T12:31:00Z",
          "status": "completed",
          "ip_address": "198.51.100.77"
        },
        "items": [
          {
            "type": "digital_good",
            "name": "Advanced React Patterns (course)",
            "quantity": 1,
            "unit_price": 149.0,
            "total_price": 149.0,
            "url": "https://learn.example.com/courses/advanced-react",
            "download_url": "https://learn.example.com/dl/arp-workbook.pdf",
            "access_granted_at": "2026-04-17T12:31:22Z"
          }
        ],
        "activities": [
          {
            "event_name": "content_accessed",
            "event_at": "2026-04-17T12:34:10Z"
          },
          {
            "event_name": "lesson_completed",
            "event_at": "2026-04-18T09:02:00Z"
          },
          {
            "event_name": "workbook_downloaded",
            "event_at": "2026-04-18T09:26:00Z"
          }
        ]
      }
    }
    ```

    **Other values:** `items[].type` is `digital_good` here. Keep appending usage `activities[]` as they happen, and send `customer_since` and `ip_address`.
  </IndustryBlock>

  <IndustryBlock id="rental" title="Rental" summary="Temporary use of an asset the customer does not own." keywords="rental car rental equipment rental boat rv camper tool rental camera electronics costume formalwear storage units furniture lease deposit damage">
    **When to use:** a customer pays to temporarily use an asset they do not own. &#x2A;*Industries:** car rental, equipment rental, boat & RV rental, tool rental, camera & electronics, costume & formalwear, storage units.

    **Highest-impact:** `policies[].policy_url` + `consented_at` (a signed, timestamped agreement) is decisive. For damage disputes, pair `has_damage_report` with `actual_pickup` vs. `actual_return`; late returns justify overage fees.

    ```json title="Rental payload"
    {
      "universal_order": {
        "customer": {
          "name": "Elena Petrova",
          "email": "e.petrova@example.com"
        },
        "order": {
          "external_id": "RNT-99114",
          "amount": 521.75,
          "currency": "USD",
          "ordered_at": "2026-05-01T15:00:00Z",
          "status": "completed",
          "confirmation_code": "CW-99114"
        },
        "rental": {
          "rental_type": "car",
          "provider_name": "Citywide Rentals",
          "booked_pickup": "2026-05-08T09:00:00Z",
          "booked_return": "2026-05-13T09:00:00Z",
          "actual_pickup": "2026-05-08T09:22:00Z",
          "actual_return": "2026-05-13T13:47:00Z",
          "duration_days": 5,
          "renter_name": "Elena Petrova",
          "rental_class": "Midsize SUV",
          "rate_per_day": 89.0,
          "total_rental_cost": 445.0,
          "protection_and_coverages": ["damage_waiver", "liability_insurance"],
          "has_damage_report": false,
          "is_no_show": false
        },
        "policies": [
          {
            "policy_type": "rental_agreement",
            "consented_at": "2026-05-08T09:22:00Z",
            "policy_url": "https://citywide.example.com/agreements/99114.pdf",
            "acceptance_method": "signature"
          }
        ],
        "charges": [
          {
            "charge_type": "fee",
            "amount": 76.75,
            "description": "Late return fee"
          }
        ],
        "addresses": [
          { "kind": "pickup", "line1": "1200 Airport Blvd", "city": "Denver" },
          { "kind": "dropoff", "line1": "1200 Airport Blvd", "city": "Denver" }
        ]
      }
    }
    ```

    **Other values:** `rental_type` also takes `motorcycle`, `rv`, `boat`, `bicycle`, `scooter`, `equipment`, `storage`, `clothing`, `furniture`, `property`, `other`. The signed agreement goes in `policies[]` (`rental_agreement`).
  </IndustryBlock>

  <IndustryBlock id="transportation" title="Transportation" summary="Moving a person or a package point to point." keywords="transportation rideshare uber lyft taxi limousine airport shuttles courier same-day delivery moving services medical transport train bus ferry gps">
    **When to use:** a customer pays to be moved point-to-point, or to have something delivered. &#x2A;*Industries:** rideshare, taxi services, airport shuttles, courier & same-day delivery, moving services, limousine services, medical transport.

    **Highest-impact:** GPS coordinates on the pickup/dropoff `addresses[]` are the strongest evidence - machine-recorded, verifiable, and nearly impossible to dispute. Pair with `actual_pickup` and `actual_dropoff`.

    ```json title="Transportation payload"
    {
      "universal_order": {
        "customer": {
          "name": "Jordan Blake",
          "email": "jordan.blake@example.com"
        },
        "order": {
          "external_id": "TRIP-7712094",
          "amount": 44.25,
          "currency": "USD",
          "ordered_at": "2026-06-11T22:14:00Z",
          "status": "completed"
        },
        "transportation": {
          "transport_type": "ride_share",
          "provider_name": "Metro Ride",
          "booked_pickup": "2026-06-11T22:10:00Z",
          "actual_pickup": "2026-06-11T22:14:38Z",
          "actual_dropoff": "2026-06-11T22:41:06Z",
          "passenger_name": "Jordan Blake",
          "passengers_count": 1,
          "driver_name": "A. Nadir",
          "service_class": "standard",
          "distance": 12.4,
          "duration_minutes": 27,
          "fare_amount": 38.75,
          "is_completed": true
        },
        "charges": [
          {
            "charge_type": "tip",
            "amount": 5.5,
            "description": "Rider tip in app"
          }
        ],
        "addresses": [
          {
            "kind": "pickup",
            "line1": "77 Harbor Way",
            "city": "Seattle",
            "country": "US",
            "latitude": 47.6062,
            "longitude": -122.3321
          },
          {
            "kind": "dropoff",
            "line1": "3410 Pine Ridge Rd",
            "city": "Bellevue",
            "country": "US",
            "latitude": 47.6101,
            "longitude": -122.2015
          }
        ]
      }
    }
    ```

    **Other values:** `transport_type` also takes `taxi`, `train`, `bus`, `ferry`, `shuttle`, `limousine`, `other`. Put `latitude`/`longitude` on both `addresses[]`, rider tips in `charges[]`.
  </IndustryBlock>

  <IndustryBlock id="service-and-saas" title="Service and SaaS" summary="Human labor, expertise, or ongoing software access." keywords="service saas software subscription consulting accounting legal cleaning home services personal training tutoring salon spa wellness medical dental repair pet care insurance recurring billing logins">
    **When to use:** a customer pays for human labor, expertise, or ongoing software access. &#x2A;*Industries:** SaaS platforms, consulting firms, accounting & legal, cleaning & home services, personal training, tutoring, salon & spa, repair services.

    **Highest-impact:** `activities[]` is the most powerful SaaS evidence - multiple logins and usage events after the charge date prove the customer used the service. Send as many as you can: logins, feature usage, API calls, settings changes, report exports.

    ```json title="Service payload"
    {
      "universal_order": {
        "customer": {
          "name": "Rachel Kim",
          "email": "rachel.kim@example.com",
          "customer_since": "2024-02-14"
        },
        "order": {
          "external_id": "SUB-2026-06-441",
          "amount": 299.0,
          "currency": "USD",
          "ordered_at": "2026-06-01T00:05:00Z",
          "status": "completed",
          "ip_address": "192.0.2.155"
        },
        "service": {
          "service_type": "professional",
          "provider_name": "Northlane Analytics",
          "delivery_method": "other",
          "client_name": "Rachel Kim",
          "booked_at": "2026-06-01T00:05:00Z",
          "service_cost": 299.0,
          "is_no_show": false
        },
        "policies": [
          {
            "policy_type": "terms_of_service",
            "consented_at": "2024-02-14T11:20:00Z",
            "policy_url": "https://northlane.example.com/terms",
            "acceptance_method": "checkbox"
          }
        ],
        "activities": [
          { "event_name": "login", "event_at": "2026-06-01T08:12:00Z" },
          {
            "event_name": "report_exported",
            "event_at": "2026-06-03T14:47:00Z"
          },
          {
            "event_name": "api_key_created",
            "event_at": "2026-06-07T10:03:00Z"
          },
          { "event_name": "login", "event_at": "2026-06-19T09:51:00Z" }
        ]
      }
    }
    ```

    **Other values:** `service_type` also takes `medical`, `dental`, `wellness`, `salon`, `fitness`, `legal`, `education`, `repair`, `cleaning`, `pet_care`, `insurance`, `other`. `delivery_method` takes `in_person`, `video`, `phone`, `home_visit`, `other`. Add `duration_minutes` for booked sessions and `cancelled_at` if the customer cancelled.
  </IndustryBlock>

  <IndustryBlock id="events" title="Events" summary="Admission to a time-bound experience at a venue." keywords="events concert promoters sports teams leagues conference organizers theater performing arts theme parks museums exhibitions festival tickets seats gate scan tours attractions">
    **When to use:** a customer pays for admission to a time-bound experience at a specific location. &#x2A;*Industries:** concert promoters, sports teams & leagues, conference organizers, theater & performing arts, theme parks, museums & exhibitions, festival organizers.

    **Highest-impact:** `scanned_at` (gate scan) and `seat_number` are the core pair - a gate-scan timestamp with a specific seat assignment is typically decisive.

    ```json title="Event payload"
    {
      "universal_order": {
        "customer": {
          "name": "Owen Fitzgerald",
          "email": "owen.f@example.com"
        },
        "order": {
          "external_id": "TCK-2026-33119",
          "amount": 258.0,
          "currency": "USD",
          "ordered_at": "2026-01-30T16:41:00Z",
          "status": "completed",
          "confirmation_code": "AF26-33119",
          "confirmation_methods": ["email"]
        },
        "event": {
          "event_name": "Aurora Fest 2026",
          "event_type": "concert",
          "venue_name": "Harbor Amphitheatre",
          "event_start": "2026-07-18T19:00:00Z",
          "event_end": "2026-07-18T23:30:00Z",
          "scanned_at": "2026-07-18T18:42:11Z",
          "is_attended": true,
          "ticket_type": "reserved_seating",
          "seat_section": "B",
          "seat_row": "12",
          "seat_number": "14",
          "ticket_number": "TIX-99213-B",
          "ticket_price": 129.0,
          "attendee_name": "Owen Fitzgerald"
        },
        "addresses": [
          {
            "kind": "venue",
            "line1": "2 Harbor Point",
            "city": "Portland",
            "country": "US"
          }
        ]
      }
    }
    ```

    **Other values:** `event_type` also takes `sports`, `theater`, `conference`, `festival`, `comedy`, `exhibition`, `theme_park`, `tour`, `attraction`, `other`. Add `rescheduled_to` if the date moved, `cancelled_at` if it was called off, and `addresses[]` (`venue`).
  </IndustryBlock>
</IndustryPicker>

## Sending data: upsert, arrays, and linking [#sending-data-upsert-arrays-and-linking]

Call `PATCH /{api_version}/disputes/{disputeId}` with the Chargeflow dispute ID to add or update enrichment. The endpoint uses **upsert** semantics: send only the fields you have.

* **Arrays are replace-in-full.** When you update an array field (for example `products` or `fulfillments`), the passed array is stored exactly as sent. To add an item, include the existing items **and** the new one; omitted items are removed. To append safely, read the current array (or use the `dispute.created` event), then `PATCH` with the full array.
* **Inline vs. linked objects.** Send full payloads, or pass IDs of objects already stored in Chargeflow to avoid duplication, e.g. `{ "transaction": "b6acc3e8408d1d6e78797725", "order": "e4d0437fb81cb881cc6bc26a" }`. Chargeflow links them and reuses their data.
* **Multiple disputes on one transaction.** Chargeflow reuses enrichment from earlier disputes on the same transaction when possible; pass existing object IDs to force explicit linking.

## Error responses [#error-responses]

For the full error reference, see [Error handling](https://docs.chargeflow.io/docs/reference/api-fundamentals/error-handling).

| Status | When it occurs                                                                                   |
| ------ | ------------------------------------------------------------------------------------------------ |
| `400`  | Both `order` and `universal_order` are present in the same request. They are mutually exclusive. |
| `422`  | Dispute status is not `needs_response`. You cannot enrich a dispute already submitted or closed. |

<Callout type="warn" title="Mutual exclusivity">
  `order` and `universal_order` cannot coexist in one request. Migrating from the legacy `order`
  field to `universal_order` means removing `order` from your payload. The `transaction` field can
  be sent alongside `universal_order`.
</Callout>

## Next step [#next-step]

<Cards>
  <Card title="Enrich a dispute" href="/docs/merchants/automation/enrich-a-dispute">
    Use the live enrichment method available today with the `order` and `transaction` payloads.
  </Card>
</Cards>