Systems and records
Ecommerce chargeback evidence data: a cross-system timeline schema
By SourceX Editorial · Reviewed by Noah Loul ·
10 sections
Short answer
A chargeback reasoning dataset needs the dispute record plus timestamped evidence from every system that shaped the right response: order lines, the policy version at checkout, inventory and fulfillment events, carrier tracking, customer messages, refunds and account activity. Store it as one bundle with a rights screen on each item and a timeline ending in the network outcome, so a validator can check order and gaps.
Record timeline
Ecommerce chargeback
Key takeaways
- The processor's dispute object is an index; the evidence lives in order, fulfillment, support, policy and account systems.
- Store items and timeline events separately, with every event pointing to the item that proves it.
- Run a rights screen on each item: no sensitive authentication data, redacted messages, pseudonymized device data, and excluded items kept as metadata.
- Refunds, partial shipments, address changes, cancellation timing and policy versions change the valid response and must be timeline events.
- Take outcomes from processor or network records, and keep merchant-side and issuer-side disputes apart.
What cross-system evidence belongs in a chargeback reasoning dataset?
A chargeback reasoning dataset needs the dispute record plus the evidence from every system that changed what the right response was: the order and its line items, the promotion or price rule in force, the inventory and fulfillment events, carrier tracking, customer messages, refunds and account activity. Each item carries a timestamp, a source system and a rights screen result, arranged as one timeline that ends in the network outcome.
The reasoning is in the joins. A dispute that says product not received is answered by fulfillment and carrier events; one that says the subscription was canceled is answered by account and policy records; one coded as card-absent fraud may be answered by prior undisputed orders from the same customer. A model only learns which evidence matters for which claim when the evidence from those systems sits in the same record with its times intact.
This page gives a schema for that record: an evidence bundle with a rights screen on every item and a timeline that lets a validator check order, gaps and contradictions. It is written for merchants and commerce operators deciding how to export their dispute history, not for issuers.
Why is the processor's dispute object only an index?
The dispute object tells you that a claim exists, its reason, its deadline and its result; the evidence lives in other systems. Stripe's public API specification is a useful map of what processors expect. Its dispute evidence object has fields such as shipping carrier, tracking number, shipping date, customer communication, refund policy and its disclosure, cancellation rebuttal, access activity log and duplicate charge explanation. Most of those are free text or uploaded files that someone assembled by hand from other tools.
The same specification shows how much of the procedure is time-bound. Its evidence details include a due-by date, a past-due flag and a submission count, described as typically allowing a single submission. Shopify's help center says evidence cannot be added after the submission deadline and that the customer's bank and card company, not Shopify, decide the outcome. A dataset that copies only the submitted packet loses the evidence the merchant had but did not send, and the timing that decided what was possible.
So treat the dispute record as the header of the bundle. Pull the evidence from its systems of record, keep what was submitted as a separate flag on each item, and keep the dispute's own dates as timeline events.
Which system holds each piece of chargeback evidence?
Map each evidence type to its system of record before you export anything. The table pairs the common evidence types with where they live in a typical commerce stack, the processor field they usually feed, the timestamp that matters and the first rights question to ask.
The join keys decide whether the bundle can be built at all. The order ID usually links the commerce platform, warehouse and help desk; the charge ID links the payment to the dispute; the customer account ID links prior orders. Check before export that each system stores the key the next one needs. A help desk that files tickets by email address only, or a warehouse that tracks shipments by its own reference, will need a mapping table, and that table belongs in the bundle's reference data so the joins can be audited later.
Clocks need the same care. Commerce platforms, carriers and processors record times in different zones and precisions, and a delivery scan stored as a local date can appear to precede a ship event stored in UTC. Normalize every timestamp to one zone, keep the original value next to it, and record the precision so a validator does not flag a same-day order as out of sequence.
| Evidence item | System of record | Processor field it feeds (Stripe naming) | Timestamp that matters | First rights screen |
|---|---|---|---|---|
| Order and line items | Commerce platform or order management system | product_description, receipt | Order placed | Customer name and address minimized or tokenized |
| Price, promotion and policy version | Pricing engine, promotions table, published policy history | refund_policy, cancellation_policy and their disclosures | Policy effective date versus order date | Company-owned text; check any marketplace terms embedded in it |
| Inventory and substitution | Warehouse or inventory system | uncategorized_text | Allocation, substitution and backorder events | Usually internal; check supplier data terms |
| Fulfillment and carrier tracking | Warehouse system, shipping platform, carrier feed | shipping_carrier, shipping_tracking_number, shipping_date, shipping_documentation | Ship, scan and delivery events | Carrier data terms; delivery photos may show people or homes |
| Customer messages | Help desk such as Zendesk or Gorgias, email | customer_communication | Message sent and received | Third-party personal data inside messages; redact before export |
| Refunds and credits | Payments ledger, order system | refund_refusal_explanation | Refund issued or refused | Internal; link by charge ID |
| Account and device activity | Identity service, web logs, fraud tool | access_activity_log, customer_purchase_ip, Visa CE 3.0 fields | Login, purchase and download events | IP addresses and device IDs are personal data in many laws; pseudonymize |
| Dispute and outcome | Processor dashboard or API | reason, status, evidence_details | Opened, due, submitted, decided | Card data: never sensitive authentication data; truncated PAN at most |
The evidence bundle and timeline schema
Store the bundle as one header record plus two child lists: evidence items and timeline events. Items describe what a document or record is; events describe when something happened. Keeping them apart lets one item support several events, such as a single carrier feed that holds the ship, scan and delivery times.
The table lists the minimum fields. Field names are suggestions; the rule that matters is that every event points to the item that proves it and every item carries its rights screen result.
| Record | Field | Purpose | Validation |
|---|---|---|---|
| Header | case_id, network, reason_category, reason_code, opened_at, due_by | Identifies the dispute and its clock | due_by after opened_at; reason code from the network's list |
| Header | outcome, outcome_at, outcome_source | The label: won, lost, accepted or withdrawn, from the processor or network | Outcome source is a processor or network record, never a merchant note |
| Item | item_id, type, source_system, captured_at, submitted | What the evidence is and whether it went to the issuer | type from a fixed list; submitted is true or false |
| Item | rights_screen: status, basis, redactions | Whether the item may leave the company and in what form | status is cleared, cleared_redacted or excluded; excluded items keep metadata only |
| Event | event_id, event_type, occurred_at, item_id | One dated fact, tied to its proof | item_id exists; occurred_at not after outcome_at unless event_type is post_outcome |
| Event | actor_type, channel | Who caused the event: customer, merchant, carrier, issuer, system | From a fixed list |
| Links | order_id, charge_id, prior_charge_ids, policy_version_id | Joins to the order, payment, prior orders and the rule in force | Every id resolves inside the bundle or in a declared reference table |
| Provenance | is_illustrative, export_date, schema_version | Separates real from synthetic and dates the export | Present on every bundle |
How do you screen each evidence item before it leaves the company?
Screen items one by one, because a single bundle mixes company records, customer data, card data and third-party content. The screen records a status, the basis for it and what was redacted, so a reviewer can see why an item is in or out.
Card data has the clearest rule. The PCI Security Standards Council's guidance on data storage says sensitive authentication data, such as the card verification code or full track data, must not be stored after authorization, even if encrypted. Its FAQ on truncation describes the first six and last four digits as the baseline for a displayed or truncated card number. A dispute export should carry a processor charge ID and, at most, a truncated number; anything more is a reason to exclude the item.
Customer messages need the most work. A support thread can name family members, include addresses and attach photos. Redact what the task does not need and record the redaction. Account and device data are useful for fraud-coded disputes but count as personal data in many privacy laws, so pseudonymize identifiers consistently within a bundle so that matches still work.
Finally, separate permission from ownership. Being able to export a carrier feed or a marketplace's dispute report does not mean the merchant may license it; the carrier's or marketplace's terms decide. Items whose terms are unclear should be excluded with their metadata kept, so the gap is visible.
Which dependent change alters the valid response?
The valid response changes whenever an event in another system changes the facts the claim depends on. These are the dependencies a reasoning dataset should make explicit, because they are where a model that reads only the dispute goes wrong:
At a glance
Which dependent change alters the valid response
- A partial shipment or substitution: an item not received claim on a split order is valid for the missing unit and invalid for the delivered ones.
- A promotion or policy version: a refund refusal is only defensible under the policy shown to the customer at checkout, so the policy version must be the one in force at the order time.
- A refund already issued: if a full refund preceded the dispute, contesting it is the wrong response; the timeline must show refund events before the dispute was opened.
- An address change after the order: a delivery to the original address can contradict a later customer request, and the order of the two events decides the case.
- A cancellation request: for subscriptions, the time of the cancellation message relative to the next renewal charge decides whether a canceled-recurring claim stands.
- Prior undisputed orders: for card-absent fraud disputes, prior orders from the same customer with matching identifiers may support a response under Visa's Compelling Evidence 3.0 rules.
Worked record and failing record (illustrative)
Both records below are illustrative and invented for this page; they contain no merchant or customer data and use counts and durations only.
Valid record. A card-absent fraud dispute is opened 40 days after an order of two units. The bundle holds the order, a policy version, one ship event and one delivery scan to the order address, and two prior orders from the same account, placed about five and eight months earlier, neither disputed. The purchase IP address and the device fingerprint on the disputed order both match the prior orders. Visa's dispute management guide describes Compelling Evidence 3.0 as requiring the same device ID, device fingerprint or IP address plus one or more additional matching elements across the prior and disputed transactions. The bundle passes the schema checks and the task label is respond with prior-transaction evidence.
Failing record. Same case, but the prior orders match the disputed order only on shipping address and email, with different IP addresses and no device data retained. A validator that encodes the rule flags it: the required device or IP match is missing, so the prior-transaction route is unavailable and the task label becomes respond with delivery evidence only or accept. The record is not discarded. It becomes a hard negative that teaches a model why matching identifiers alone are not enough.
Neither example predicts the issuer's decision. Visa's own guidance says that following its examples does not ensure the evidence will be accepted, which is why the outcome field must come from the processor or network record.
Use the pair to set up two task types. A selection task gives the agent the full bundle and asks which items to submit for the stated reason code; it is scored against the rule and the items available. An outcome task asks whether the case was won or lost, and it should be held out by date, because issuer behavior and network rules change over time and an agent tested on the same months it was trained on will look better than it is.
Validator checks every bundle should pass
- Every event has an item_id that exists in the bundle, and every item is referenced by at least one event or flagged as context only.
- Events are in time order, and no pre-outcome event is dated after outcome_at.
- The order was placed before the charge, the charge before the dispute, and any refund event is checked against the dispute open date.
- The policy version's effective window contains the order time.
- Submitted items were captured on or before the submission time; anything captured later is marked not submitted.
- No item contains sensitive authentication data, and any card number is truncated.
- Every excluded item keeps type, source and timestamps so the gap stays visible.
- The outcome comes from a processor or network record and is one of a fixed set of values.
- Pseudonymous identifiers are consistent within the bundle so matches across prior orders survive redaction.
Keeping merchant disputes apart from issuer billing-error cases
Label which side of the dispute the records come from, because the rules and the evidence differ. Merchant-side records show what the seller knew and submitted. Issuer-side records follow consumer protection rules: under Regulation Z's billing error provisions, a cardholder's written notice must reach the creditor within 60 days of the first statement showing the error, the creditor must acknowledge it within 30 days, and resolution must follow within two complete billing cycles and no later than 90 days.
A dataset that blends the two will teach a model to treat an issuer's investigation clock as the merchant's response window, or the reverse. Keep a side field on the header and, if you hold both, link them only through the network case reference.
Licensing a chargeback evidence history
Merchants with several years of disputes and the linked order, fulfillment and support records hold the cross-system history this schema describes. SourceX can carry selected dispute histories through rights review, preparation and delivery as a licensed AI dataset, and an export too large to send can remain in the merchant's own storage or go out on encrypted drives instead of being hosted.
Nothing ships until the merchant has approved which dispute records are in scope, agreed the terms and signed. A merchant's first step is a brief company assessment, with no dispute files uploaded.
Frequently asked questions
What should a rights screened evidence bundle and timeline schema include?
A header for the dispute with its reason, deadline and network outcome, a list of evidence items with source system, capture time, submitted flag and rights screen result, and a list of dated events each tied to the item that proves it. Links to the order, charge, prior charges and policy version complete it.
Which dependent item, rule or inventory change alters the valid response?
Partial shipments, substitutions, refunds issued before the dispute, address changes, cancellation timing and the policy version shown at checkout all change the right answer. The schema records them as timeline events so a model can see their order relative to the dispute.
What do valid and invalid examples of the structure look like?
A valid bundle has every event tied to an existing item, events in time order and an outcome from the processor. An invalid one might rely on prior orders that match only on email and shipping address, which fails Visa's requirement for a device or IP match under Compelling Evidence 3.0.
Can chargeback records include card numbers?
They should carry a processor charge ID and at most a truncated card number. PCI guidance says sensitive authentication data such as the card verification code must not be stored after authorization, even encrypted, so any item containing it should be excluded.
Is the submitted evidence packet enough for a training dataset?
No. The submitted packet shows only what the merchant chose to send before the deadline. The reasoning signal comes from the full set of linked records and their timestamps, including evidence that existed but was not submitted.
Sources
- Stripe's OpenAPI specification defines dispute evidence fields (shipping, customer communication, refund and cancellation policy, access activity log) and evidence details (due_by, past_due, submission_count, typically one submission). Source
- Visa's dispute management guidelines describe Compelling Evidence 3.0 matching (device ID, fingerprint or IP address plus another element) and state that its examples do not ensure acceptance. Source
- Shopify's help center says no further evidence can be submitted after the deadline and that the customer's bank and card company decide chargeback outcomes. Source
- PCI SSC guidance says sensitive authentication data must not be stored after authorization, even if encrypted. Source
- PCI SSC's truncation FAQ treats the first six and last four digits as the baseline for truncated card numbers. Source
- Regulation Z section 1026.13 sets the 60-day billing error notice, 30-day acknowledgment and two-billing-cycle, 90-day resolution limits. Source
See if your company qualifies
A short company assessment. No data uploads are needed.