Skip to content

AI uses for records

Ecommerce substitution decision data: training agents to choose a valid substitute

By SourceX Editorial · Updated

10 sections

Short answer

Build substitution training cases as linked records, not product pairs: the ordered item, the customer's replacement setting and backups, hard constraints such as allergens and size, the stock state at pick time, the promotion and policy versions in force, the candidates considered, the action taken, the customer's approval or rejection and what happened after delivery. Only then can an agent learn which substitute was valid.

Agent run

Ecommerce substitution

This page covers ecommerce substitution decision data: training agents to choose a valid substitute.Illustrative

Key takeaways

  • A product pair shows similarity; a linked case record shows whether a substitute was valid and welcome.
  • Check hard constraints first: declared allergens, dietary claims, age restrictions, recalls and declared net content.
  • Record the stock state at decision time from the pick log, not what the product page advertised.
  • Keep three customer signals apart: the setting before, the approval during and the behavior after delivery.
  • Silent acceptance and timed-out approvals are unconfirmed labels, and returns turn approvals into negatives.

How do you build training cases for valid substitutions when stock runs out?

Build each case around one decision: a line on an order could not be filled as ordered, and someone chose to substitute, refund, delay or ask the customer. Link that decision to the facts that made one choice valid and another wrong, and to what the customer did about it.

The common shortcut is a table of original and replacement product pairs. It looks like substitution data and teaches a model item similarity. It cannot teach validity, because validity depends on facts outside the pair: whether this customer allowed substitutions, which allergens they must avoid, what was actually on the shelf at that minute, whether a promotion tied the item to another line and whether the customer later returned the replacement.

The rest of this page sets out those facts as a dataset specification, with the rules that change the valid action and a worked case. Examples are illustrative; the field list is meant to be used as is and trimmed to your systems.

Why is a substitution a constrained choice, not a similar-item lookup?

A valid substitute must pass hard constraints before any preference matters. A hard constraint is a rule the replacement cannot break: a declared allergen the original did not contain, a dietary claim the customer relies on, an age-restricted product, a recalled lot, or a size that changes the quantity materially. Soft preferences, such as brand loyalty or tolerance for a larger pack, decide between candidates that already pass.

Allergens show why attributes must be explicit fields. FDA lists nine major food allergens in the United States, with sesame added as the ninth by the FASTER Act and effective for labeling from January 1, 2023. A substitute that adds one of them can be unsafe for a customer even when it looks nearly identical, so the dataset needs allergen declarations for both items as recorded at the time.

Size is subtler. Under GS1 rules, a change to the declared net content of a consumer product calls for a new GTIN, so two items that share a name and photo can be different trade items. Record net content and unit of measure, not only the product title, and treat a size change as a constraint check, not a cosmetic difference.

Which stock state was true at the moment of the choice?

Record the stock state the picker or system saw when the decision was made, with a timestamp and location, not the state shown on the product page. Listing availability and pick-time availability diverge constantly, and a model trained on the wrong one learns to substitute items that were never there.

Commerce systems model this in layers. Schema.org's ItemAvailability values, such as InStock, OutOfStock, BackOrder and Discontinued, describe what an offer advertises. Shopify's inventory model separates states at a location, including available, committed to orders, reserved, incoming and on hand, and treats committed quantities as managed by the platform through order creation and fulfillment. Neither tells you what was physically pickable at 10:42 on a given day; the pick log or store system does.

Capture three times for each case: when the order was placed, when the shortage was detected and when the substitution decision was made. The gaps between them explain many bad substitutions, because candidates that were available at checkout had sold through by pick time.

The substitution constraint and customer preference dataset

Use this specification for one case record per shorted order line. Field groups are linked by order id, line id and decision id; each group says where the data usually lives and why it can change the valid action.

The substitution constraint and customer preference dataset
Field groupFieldsUsual sourceWhy it changes validity
Ordered lineLine id, item id and GTIN, quantity, unit, net content, brand, categoryOrder management systemDefines what the customer asked for and the size baseline
Customer settingReplacement policy for the line, named backup items, free-text note flag, policy source and timestampCheckout and account settingsWhether substitution is allowed at all, and which items are pre-approved
Hard constraintsDeclared allergens of original, dietary and certification claims, age restriction, recall flagProduct information and compliance recordsA candidate breaking any of these is invalid regardless of similarity
Soft preferencesBrand tolerance, size tolerance as a ratio, past accepted and rejected substitutes for this customerOrder historyRanks candidates that pass every hard constraint
Stock snapshotState per candidate at decision time, location, timestamp, source of the readingPick log, store or warehouse systemShows which candidates were really available
Rule versionsPromotion id and terms version, bundle or multi-buy link, quantity limits, substitution policy versionPricing and policy engineA promotion or bundle can make a like-for-like swap break another line
Candidate setCandidates considered with rank, rule that excluded each rejected candidatePicker app or recommender logTeaches why options were ruled out, not only what was chosen
ActionSubstitute, refund, delay with notice, contact customer, actor role, timeFulfillment eventsThe decision being learned
Customer outcomeApproved, rejected, no response window, return, refund request, complaint, repeat purchase of originalOrder status, returns and support systemsSeparates accepted substitutes from tolerated ones

How do you record the customer's say before, during and after the order?

Record three distinct signals, because each answers a different question. The setting before the order says what the customer allowed. The response during fulfillment says whether they agreed to this specific swap. The behavior afterward says whether the swap actually worked for them.

Platform APIs make the first two concrete. Instacart's Connect documentation describes a per-item replacement policy with three values: no replacements, replace only with customer-approved alternatives, and let the shopper choose. It also states that when specific replacement items are supplied, the policy must be the customer's-choice value, and it describes a flow where a shopper suggests a replacement and the customer approves it or asks for a refund. Whatever your platform, store the policy value and the approval event with their timestamps.

The third signal is the one most datasets lose. A replacement that was approved in the app and then returned, refunded through support or followed by a complaint was not a good substitute. Link returns and support tickets back to the line and decision ids so the label reflects the outcome, not the click.

Which promotion, order change or delay rule alters the valid action?

Check the rules around the line, not just the line. A multi-buy promotion can make a cheaper single substitute leave the customer worse off, a bundle can tie a shorted item to another line that should then also change, and a quantity limit can make a larger pack invalid. Record the versions of these rules in force at decision time; a policy edited the following week does not explain last week's decision.

Customer edits mid-fulfillment also change the answer. If the customer removed or added lines after checkout, the valid substitute may be no substitute at all. Keep the order edit events with their times.

Some cases should end in a delay or cancellation rather than a swap. For merchandise ordered by mail, internet or phone, the FTC's business guide explains that a seller who cannot ship within the promised time, or within 30 days if no time was stated, must offer the customer the choice to agree to the delay or cancel for a prompt refund. Grocery delivery operates differently, but for shipped goods the dataset should record when the delay route was taken and whether the required notice was given.

  • Promotion linked to the shorted line: record the promotion id and whether the substitute kept the customer's benefit.
  • Bundle or recipe set: record the sibling lines and whether they were adjusted.
  • Quantity or pack-size limits: record the limit and how the substitute compared.
  • Customer edits after checkout: record edit times relative to the shortage.
  • Shipped goods with no valid substitute: record the delay notice, the customer's choice and the refund event.

Worked example: a shorted oat milk line (illustrative)

Illustrative only. A customer orders two cartons of a 1.75-liter oat milk. The account's replacement setting for the line is replace only with approved alternatives, with one named backup: a different brand's oat milk in the same size. The customer's history shows two earlier rejections of almond milk substitutes.

At pick time, 47 minutes after checkout, the original is out of stock. The backup brand shows available, but the pick log reads zero on the shelf. Three candidates remain: the original brand in a 1-liter carton, an oat and almond blend whose label declares tree nuts, and the backup brand in a smaller size.

The tree nut candidate fails a hard constraint because the original declared none. The two size changes pass hard constraints, but the customer's setting requires approval. The shopper suggests three 1-liter cartons of the original brand, the closest volume without exceeding the order; the customer approves within 4 minutes. Eleven days later the customer reorders the original 1.75-liter size, with no return or complaint. The case record carries all of this: setting, constraints, the excluded candidate with its rule, the stock reading, the approval and the outcome.

Labels that look like success but are not

Silent acceptance is the most common false label. If the customer's setting let the shopper choose and nobody complained, the record says the substitute was accepted, but the customer may have simply not noticed or not bothered. Label these as unconfirmed rather than positive, and weight them accordingly.

A timed-out approval is another. When a customer does not respond within the approval window and the system defaults to a refund or a swap, the outcome reflects the timeout rule, not a preference. Keep the response status as its own value.

Finally, an approved substitute that triggers a support contact or return within a few days is a negative example, even though the order shows complete. Without the return and support links, a dataset will rate it as a success.

Which cases to leave out, and when retail operations or privacy experts need to weigh in

Leave out cases where the stock snapshot is missing or recorded after the decision, where constraint attributes for either item are absent, or where the customer outcome cannot be linked. These cases teach a model to guess at the facts that matter most.

Bring in a retail operations expert to confirm which rules were really in force and how pickers worked in practice, since written policy and floor practice often differ. Bring in a rights and privacy reviewer before any extract, because order histories, preference notes and support contacts are consumer data, and some carry health signals such as allergen or dietary choices. Free-text substitution notes in particular can contain names, addresses and medical detail and should be dropped or reviewed after redaction.

When substitution histories become a dataset others can license

Retailers, delivery operators and commerce software companies that have kept these links hold decision data that is hard to reconstruct elsewhere. Licensing it raises separate questions from building it: who controls the records, what customer terms and merchant contracts allow, and what privacy law permits. Clean de-identification does not answer those questions on its own.

Retailers that license selected substitution records to AI developers through SourceX leave the rights review, contracting, preparation and delivery to SourceX. The business approves the scope and signs before anything is delivered, and de-identification is carried out by SourceX through approved processing routes. A retailer can learn whether it qualifies from a short assessment that asks for no uploaded data.

Frequently asked questions

What is ecommerce substitution decision data?

It is the record of what happened when an ordered item could not be supplied: the customer's replacement setting, the constraints on the item, the stock state at the time, the candidates considered, the action taken and the customer's response and later behavior. Linked together, these records show which substitutes were valid, not just similar.

Why are original and replacement product pairs not enough?

A pair shows that a swap happened, not whether it was allowed or welcome. Validity depends on the customer's setting, allergen and size constraints, real stock at pick time and promotions in force, and quality depends on whether the customer approved and kept the replacement.

What replacement settings do grocery platforms record?

Instacart's Connect API, for example, describes three per-item policies: no replacements, replace only with customer-approved alternatives, and let the shopper choose. Store the setting value and its timestamp for each line, along with any named backup items the customer picked.

How should allergens be handled in substitution data?

Record declared allergens for both the original and every candidate as they were labeled at the time, and treat adding a major allergen as a hard constraint that makes the substitute invalid. In the United States FDA recognizes nine major food allergens, including sesame since 2023.

How do you label a substitution the customer never responded to?

Keep no response as its own status rather than treating it as approval, and record the default the system applied when the window closed. Then link any later return, refund or complaint so the final label reflects what the customer actually did.

Sources

  • Instacart Connect documents per-item replacement policies (no_replacements, users_choice, shoppers_choice) and requires users_choice when replacement items are supplied. Source
  • Instacart's replacement flow lets a shopper suggest a replacement that the customer approves or rejects in favor of a refund. Source
  • The FTC's business guide to the Mail, Internet, or Telephone Order Merchandise Rule covers shipping within the stated time or 30 days and offering consent to delay or cancellation with a prompt refund. Source
  • Schema.org's ItemAvailability enumeration includes InStock, OutOfStock, BackOrder and Discontinued for an offer's availability. Source
  • FDA explains that the FASTER Act made sesame the ninth major food allergen, effective January 1, 2023. Source
  • Shopify's inventory model separates available, committed, reserved, incoming and on-hand states at a location, with committed managed by Shopify. Source
  • GS1 GTIN management rules call for a new GTIN when the declared net content of a product changes. Source

See if your company qualifies

A short company assessment. No data uploads are needed.

See if your company qualifies