Industry Enrichment

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.

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

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

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.

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.

The order object also supports confirmation fields that strengthen evidence:

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

Accommodation

When to use: a customer pays to occupy a physical space for a defined period. Industries: hotels & resorts, vacation rentals, hostels, serviced apartments, bed & breakfasts, campgrounds & glamping, timeshare resorts.

Block accommodation: property_name, property_type (hotel, vacation_rental, hostel, b_and_b, …), room_type, booked_check_in/booked_check_out (date), actual_check_in/actual_check_out (timestamp), number_of_nights, guest_name, guests_count, rate_per_night/total_accommodation_cost, is_no_show. Cancellation and refund terms live in policies[].

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.

Flights

When to use: a customer pays for scheduled air transportation between two points. Industries: commercial airlines, charter flights, private aviation, helicopter tours, air ambulance, scenic flights.

Block flight: airline_name, airline_code (3-char ICAO), flight_number, ticket_number, departure_airport/arrival_airport (4-char ICAO), booked_departure/booked_arrival, actual_departure/actual_arrival (timestamp), passenger_name, cabin_class (economy, premium_economy, business, first, other), seat_number, fare_amount, checked_bags_count, is_checked_in, boarded_at, is_no_show.

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.

Dining

When to use: a customer pays for food or beverages prepared and served, on-premise or delivered. Industries: restaurants, cloud kitchens, catering, food delivery platforms, meal kit subscriptions, wine & spirits clubs, bars & lounges.

Block dining: venue_name, venue_type (restaurant, bar, cafe, catering, food_truck, other), reservation_at (timestamp), guests_count, guest_name, meal_type (breakfast, brunch, lunch, afternoon_tea, dinner, drinks, tasting_menu, other), total_dining_cost/price_per_guest, is_no_show. Gratuity goes in charges[] (charge_type: tip); delivery fees fit charges[] (charge_type: fee).

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.

E-commerce

When to use: a customer pays for a physical product shipped to an address. Industries: online retail, marketplace sellers, subscription boxes, print-on-demand, wholesale & B2B, dropshipping.

Uses items[]: type (physical_good; also digital_good, food_delivery, grocery, other), name, sku, quantity, unit_price, total_price, url, image_url, tracking_number. Add addresses[] (kind: shipping) and ip_address.

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".

Digital goods

When to use: a customer pays for a non-physical product delivered electronically. Industries: online courses, software licenses, digital art & NFTs, e-books & audiobooks, stock photos & media, in-app purchases, gaming credits, digital subscriptions.

Uses items[]: type (digital_good), name, quantity, unit_price, total_price, url, download_url, access_granted_at (timestamp). Add ip_address, customer_since, and usage activities[].

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.

Rental

When to use: a customer pays to temporarily use an asset they do not own. Industries: car rental, equipment rental, boat & RV rental, tool rental, camera & electronics, costume & formalwear, storage units.

Block rental: rental_type (car, motorcycle, rv, boat, bicycle, scooter, equipment, storage, clothing, furniture, property, other), provider_name, booked_pickup/booked_return, actual_pickup/actual_return (timestamp), duration_days, renter_name, rental_class, rate_per_day/total_rental_cost, protection_and_coverages[] (e.g. damage_waiver, liability_insurance), has_damage_report, is_no_show. The signed agreement goes in policies[] (rental_agreement); use addresses[] (pickup/dropoff).

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.

Transportation

When to use: a customer pays to be moved point-to-point, or to have something delivered. Industries: rideshare, taxi services, airport shuttles, courier & same-day delivery, moving services, limousine services, medical transport.

Block transportation: transport_type (ride_share, taxi, train, bus, ferry, shuttle, limousine, other), provider_name, booked_pickup, actual_pickup/actual_dropoff (timestamp), passenger_name, passengers_count, driver_name, service_class, distance, duration_minutes, fare_amount, is_completed. Use addresses[] (pickup/dropoff) with latitude/longitude; rider tips go in charges[].

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.

Service and SaaS

When to use: a customer pays for human labor, expertise, or ongoing software access. Industries: SaaS platforms, consulting firms, accounting & legal, cleaning & home services, personal training, tutoring, salon & spa, repair services.

Block service: service_type (medical, dental, wellness, salon, fitness, professional, legal, education, repair, cleaning, pet_care, insurance, other), provider_name, delivery_method (in_person, video, phone, home_visit, other), client_name, booked_at, duration_minutes, service_cost, is_no_show, cancelled_at. Add customer_since, terms and cancellation in policies[], and usage activities[].

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.

Events

When to use: a customer pays for admission to a time-bound experience at a specific location. Industries: concert promoters, sports teams & leagues, conference organizers, theater & performing arts, theme parks, museums & exhibitions, festival organizers.

Block event: event_name, event_type (concert, sports, theater, conference, festival, comedy, exhibition, theme_park, tour, attraction, other), venue_name, event_start/event_end, scanned_at (timestamp), is_attended, ticket_type, seat_section/seat_row/seat_number, ticket_number, ticket_price, attendee_name, rescheduled_to, cancelled_at. Use addresses[] (venue).

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.

Find your industry

If your platform spans multiple domains, send the domain that best matches the specific transaction being disputed. An OTA uses Accommodation for hotel bookings and Flights for air tickets, even from the same platform.

Don't see your exact industry? Match the domain to the commercial story behind your transaction.

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

For the full error reference, see Error handling.

Next step