Skip to content

Systems and records

Approved is not finished: building a supplier return workflow dataset

By SourceX Editorial · Reviewed by Noah Loul ·

10 sections

Short answer

A supplier return workflow dataset should treat the return authorization as the first of several decisions, not the answer. A correct RMA still leaves open the condition evidence, the reason code, the credit or replacement terms, the disposition and who approved. In this article's audit of five open-source systems, 10 of 25 such elements had a typed field and none named the approver, so episodes must recover them from linked records or mark them missing.

Provenance trail

Approved is not finished

This page covers approved is not finished: building a supplier return workflow dataset.Illustrative

Key takeaways

  • An RMA number proves permission to send goods back; it does not prove what arrived, what the remedy covered, where the goods went or who agreed.
  • Five open-source systems audited at pinned commits store 10 of 25 of those elements as typed fields, and none has a typed field naming who approved a return.
  • The one audited system that models a return to a supplier, OSPOS, records it as a negative receiving with a comment and none of the five elements typed.
  • Regulated returns set the bar: 21 CFR 211.204 requires the reason, the quantity, the date of disposition and the ultimate disposition for returned drug products.
  • Grade return decisions for completeness as well as correctness; a right authorization with open obligations is a partial answer.

What does a correct return authorization still leave open?

Everything that happens after permission. A return authorization says the goods may go back; it does not say what condition they arrived in or what proves it, which coded reason applies, whether the remedy is a credit, a replacement or a repair and for how many units, where the goods go next, or who approved each of those calls. A return can be authorized correctly and still end with a short credit, miscounted stock and nobody accountable for the exception.

That is the trap in a supplier return workflow dataset built from RMA headers. A model trained on authorizations learns to say yes or no. It does not learn to close the obligations that follow, and an evaluation that grades only the authorization will score a half-finished return as a success.

The decision this page supports is practical: which fields and linked records one return episode needs before it can train or test a procurement agent, how to find episodes where the gap already exists, and how to grade an answer that is right but incomplete. Physical return, inspection, remedy, disposition and closure are tracked as separate stages throughout.

Five obligations that outlive the authorization, and where rules name them

The rules that govern returns already treat these as separate obligations rather than details of the RMA. X12's catalog describes the 180 transaction set, Return Merchandise Authorization and Notification, as the electronic message for sending goods back to a vendor, usable to request a return, to authorize or disposition one, or to give notice of one (paraphrased from x12.org). Disposition is named as its own function.

At a glance

Five obligations that outlive the authorization, and where rules name them

Commercial law separates disposition from authorization too. Under UCC section 2-603, a merchant buyer holding rightfully rejected goods, where the seller has no agent or place of business at the market of rejection, generally has to follow the seller's reasonable instructions about them; under section 2-604, if no instructions arrive within a reasonable time, the buyer may store, reship or resell the goods for the seller's account (both paraphrased from the Legal Information Institute's text). The goods can sit at the buyer while the decision about them belongs to the seller. This is general information, not legal advice.

Regulated goods show the full bar. For returned drug products, 21 CFR 211.204 requires records that include the product's name and label potency, the lot or batch number, the reason for the return, the quantity returned, the date of disposition and the ultimate disposition, and it says a product whose holding or shipping conditions cast doubt on its quality "shall be destroyed unless examination, testing, or other investigations prove otherwise." FDA guidance on the Drug Supply Chain Security Act describes a wholesale distributor's duty to verify the product identifier of a saleable returned product before distributing it further (paraphrased).

Taken together, five elements have to be recorded for a return to be finished, each with what a record needs:

  • Condition evidence: what was found on receipt and what proves it, such as a count, an inspection result, photos or a test record, kept apart from what the requester declared.
  • Reason code: a cause from a controlled list in force on the date, stored beside any free text, so defect rates per supplier can be counted.
  • Credit or replacement terms: the remedy type, the units and value it covers, and whether it rests on announced or counted units.
  • Disposition: restock, return to vendor, rework, scrap or hold, with who instructed it and any verification required before resale.
  • Approver: who approved the authorization and each later exception, by role and identifier, at the time of the decision.

What five open-source systems let a return record hold

Not much. Audited at pinned commits, five open-source commerce and point-of-sale systems store 10 of the 25 elements as typed fields, and none has a typed field naming who approved a return. Spree 6 types four elements, nopCommerce and OpenCart three each, and PrestaShop and Open Source Point of Sale (OSPOS) none.

The systems were chosen because their return records are public and inspectable. Spree's 6.0 returns model, on the main branch at the audited commit, replaced a three-record chain of return authorization, customer return and reimbursement with one record whose states run from requested through approved, received and refunded, or canceled, with approval and receipt timestamps and a per-line resellable flag. nopCommerce keeps a return request whose reason and requested action are stored as text strings rather than keys to its reason and action lists, with a customer-uploaded file and a quantity returned to stock. OpenCart codes the reason and the action, flags whether the product was opened and logs status history with no user column. PrestaShop stores the customer's explanation as free text and a state. OSPOS has no return object at all: a return to a supplier is a receiving saved in return mode, with quantities negated in the controller.

Three details matter for dataset design. Spree's resellable flag defaults to true, so a disposition exists even when nobody decided one. OpenCart's seeded action list mixes progress and remedy in one field: Waiting for return, Credit Issued, Replacement Sent, Refunded. And Spree's own actor migration gives orders a created_by, an approver and a canceler, but returns only a created_by, the staff member who opened one.

The table shows, for each system, which elements are typed, which survive only as free text, a label stored as text, a timestamp or a proxy, and which are absent:

What five open-source systems let a return record hold
System and return recordTyped fieldPartial: text, label, timestamp or proxyNothing
Spree 6: return and return linesCondition (received quantity, the warehouse's count), reason (reason list key), credit value per line, disposition (resellable, default true)Approver (approved_at timestamp; created_by is the opener)None of the five
nopCommerce: return requestCondition (uploaded file id), remedy type (status values ItemsRepaired and ItemsRefunded), disposition (quantity returned to stock)Reason and requested action (stored as text, not list keys); approver (free-text staff notes)None of the five
OpenCart: return and status historyCondition (opened flag, declared by the requester), reason and action (list keys)Approver (status history timestamps, no user)Disposition
PrestaShop: order return and detailNoneReason (customer's free-text question); approver (update timestamp)Condition, credit or replacement terms, disposition
OSPOS: receiving in return mode (to supplier)NoneReason (comment); credit (line cost only); approver (employee who keyed it)Condition, disposition
A five by five grid of return-record elements against five open-source systems: filled cells for typed fields total 10 of 25, and the row for who approved the return has no typed field in any system.
Typed, partial and missing return elements in Spree 6, nopCommerce, OpenCart, PrestaShop and OSPOS at pinned commits, from the author's schema audit.

Six signatures that show an authorized return was never finished

The gap leaves traces in ordinary fields, so a dataset builder can find unfinished returns before sampling. Each signature below is a query with a numerator and a denominator; report them per supplier and per year, because a rate that moves with a system migration says more about the system than the suppliers.

At a glance

Six signatures that show an authorized return was never finished

Spree's documentation states the principle behind the second and third signatures plainly: a delivery reporting arrival "never receives the return: arrival is not inspection." Its receiving step takes the quantities the warehouse counted, because, in the documentation's words, "A customer says three items are coming; two arrive; one of those can't be sold again." The signatures to run:

  • Approved, never received: an approval timestamp with no receipt inside the agreed window.
  • Received, no condition: a receipt with no inspection result, photo, test record or condition code.
  • Credit on announced units: credited quantity equal to the requested quantity while the counted quantity differs.
  • Default disposition: lines still at the default disposition, such as a resellable flag left true, while the reason says defective.
  • Closed without an approver: a completed status carrying only a creator, a timestamp or nothing.
  • Reason only in prose: free text where a code list exists, or a stored label that no longer matches any current list entry.

The return decision packet and its constraint matrix

The packet is the unit of the dataset: one return episode, linked by the supplier's RMA number and the original order line, holding the request, the constraints in force, each decision and the realized outcome, with every stage kept separate. Free text stays beside codes rather than replacing them, and the policy or supplier agreement version in force travels with the episode.

The constraint matrix says, for each element, what binds the decision, what evidence the packet must hold, who may decide and what goes wrong when the element is missing. Use it as the field specification for extraction and as the checklist a grader applies:

The return decision packet and its constraint matrix
ElementConstraint that binds itEvidence in the packetWho may decideFailure if missing
AuthorizationReturn window, warranty or supplier agreement, and the supplier's own RMA rulesRequest, supplier RMA number and the policy version in forceBuyer's returns owner, then the supplierShipment refused or never credited
Condition evidenceInspection criteria in the supplier agreement or quality planDated count, inspection result, photos or test recordReceiving inspector or quality leadCredit dispute with no proof
Reason codeCode list in force on the decision dateCode plus the original free textRequester proposes, inspector confirmsDefect rates per supplier cannot be counted
Credit or replacement termsAgreed remedy, restocking charges and approval limitsRemedy type, units, value and whether units were announced or countedBuyer within approval limits; supplier acceptsCredit short, duplicated or paid on units never sent
DispositionSeller's instructions and any verification required before resaleDisposition code, who instructed it and the verification recordSupplier instructs; buyer or warehouse executesDefective stock restocked, or goods scrapped against instructions
Approval of exceptionsDelegation of authority for returnsApprover identifier, role, time and the exception reasonThe role named in the delegationNobody accountable for the exception

Correct, complete, or correct but incomplete: grading a return decision

Grade every episode on two axes: whether each decision matches the realized correct outcome, and whether every obligation was closed or explicitly handed to a named owner. An answer that gets the authorization right and leaves the rest open is a partial answer, and the benchmark should say so.

At a glance

Correct, complete, or correct but incomplete: grading a return decision

Illustrative episode: a distributor asks a supplier to take back 50 valves with a seat defect, and the supplier issues an RMA for 50. Only 46 ship, because 4 were already installed. Inspection confirms the defect on 40 and finds installation damage on 6; the supplier instructs scrap for the 40 and credits 40. Agent A requests the RMA with the right reason, asks for credit on 50 and marks the case done. Agent B makes the same request, asks for condition photos, holds the credit until the count, records the supplier's scrap instruction, routes the 6 damaged units to the category manager and flags the 4 that never shipped. Both authorizations are correct; only B's return is complete.

Four labels cover the outcomes a grader will see. Report the share of episodes in each, and treat an agent that raises correctness while lowering completeness as no better than the one it replaced:

  • Correct and complete: every decision matches the outcome and every obligation is closed or handed off with an owner.
  • Correct but incomplete: the authorization and reason are right, but condition, remedy basis, disposition or approval is left open.
  • Complete but wrong: every field is filled, but a decision contradicts the evidence, such as the wrong reason code or remedy.
  • Premature: an action taken before its evidence existed, such as a credit issued before receipt or a restock before inspection.

Is the fastest credit the right answer? Testing the shortcut

Usually not. The fastest path, crediting the announced quantity at authorization and restocking on arrival, breaks a constraint in many episodes: it pays for units that never shipped, returns damaged goods to sellable stock, and skips the supplier's say over disposition that UCC section 2-603 can give it for rejected goods.

The alternative explanation for a slow return deserves a fair test, because sometimes the delay is waste. Compare each slow episode's extra steps with the constraint that required them. If no constraint explains a step, the slow path was not the right answer either; if one does, as with verification before resale of a saleable drug return, the quick path was the error.

A dataset that contains only fast, clean returns will teach speed. Include episodes where the slower path was correct, label the constraint that made it correct, and keep denied, withdrawn and partly credited returns in the population so the model sees how often the quick answer fails.

Requesting return episodes instead of return tables

Ask for episodes, not tables. A useful request covers every return in a defined period, including denied, withdrawn and partly credited ones, with the supplier RMA, the buyer's return order, receipt and inspection records, the remedy, the disposition instruction, the approvals and the accounts payable match, linked by the RMA number and order line and de-identified before delivery.

At a glance

Requesting return episodes instead of return tables

SourceX sources datasets on request from U.S. businesses rather than holding them in stock, so a request for return episodes starts from a written specification: buyers describe scope, volume, language, format, timing and licensing needs through the request form. Add the completeness test from this page as the request's acceptance test, along with these items:

  • Population: all returns opened in the period, with counts of denied, withdrawn and partly credited returns stated.
  • Stage timestamps: requested, authorized, shipped, received, inspected, remedied, dispositioned and closed, each nullable rather than backfilled.
  • Codes with versions: reason and disposition codes plus the code list in force on each decision date.
  • Approvals: approver role and a stable pseudonymous identifier for the authorization and each exception.
  • Linkage: RMA number, order line, receipt and credit memo keys, with the share of episodes fully joined reported.
  • Exclusions: any filter applied before delivery, listed with the number of episodes it removed.

Where this design stops

The field audit reads schemas, not live data, and that sets its limits:

  • A typed field is not a filled field; companies can leave typed columns empty or at their defaults.
  • Extensions and custom fields can add an approver or a condition code to any of these systems; the audit covers the core schema at one commit.
  • Four of the five systems model returns from customers to a seller; only OSPOS models a return to a supplier, so the supplier side rests on one system plus the X12, UCC and FDA sources.
  • Commercial ERP and procurement suites were not audited.
  • The legal and regulatory sources are summarized for dataset design and are not legal advice; disposition rules vary by industry, contract and jurisdiction.

How the field audit was counted

Repositories and commits: spree/spree 75e29731b039e1b8211b2a6e62b17b6b695838f1, nopSolutions/nopCommerce 221305873bc81c47981b2e510b2e9bed7e5b2076, opencart/opencart 9d73cf2e5d6665dc24dc63469ecaaaaa23c364ec, PrestaShop/PrestaShop 52a8b2e7d36a4c755c0e876168646b3a2253752b and opensourcepos/opensourcepos b07f5e3ebb38889a800974c466109452450fba69, sparse-cloned on 2026-10-27. Files read: Spree's 6.0 returns migration plus every later migration in name order, applying column additions (including the actor migration's created_by_type), removals and renames to the two return tables; nopCommerce's ReturnRequest entity; OpenCart's schema helper for the return and return_history tables and its seed SQL for the action list; PrestaShop's order_return and order_return_detail tables; OSPOS's initial schema plus every later top-level SQL script in name order, applying column additions, renames and drops to its two receiving tables, and the controller line that negates quantities in return mode.

Scope rule: the return record, its line records and any table pointing to the return by foreign key. Claims, exchanges, refunds and credit slips held in separate records were excluded. Counting rule: an element counts as typed when an in-scope column of boolean, numeric quantity or amount, enumerated or foreign-key type (to a reason or action list, a file or a user) records it. Free text, a label stored as text, a timestamp without an actor and an actor column that records who keyed the record count as partial and score zero. The script printed every column it parsed, including those mapped to none of the five, so a reviewer can check the mapping.

Judgment calls, stated so they can be challenged: nopCommerce's uploaded file and OpenCart's opened flag were counted as condition evidence although both come from the requester; Spree's received quantity was counted as condition evidence because it is the warehouse's count, kept apart from the declared quantity; nopCommerce's enumerated status was counted as credit or replacement terms because its values include ItemsRepaired and ItemsRefunded (without it the total would be 9); OSPOS's line cost was counted as partial because it records purchase cost, not a remedy; Spree's created_by was counted as partial because it names the opener of a staff-created return and is empty for customer-created ones. Result: 10 typed cells of 25, 0 of 5 for the approver.

Frequently asked questions

What is the difference between a return authorization and a completed return?

An authorization is permission to send goods back, usually carrying an RMA number. A completed return also records what arrived and in what condition, the coded reason, the remedy and the units it covers, where the goods went, and who approved each step. Many records stop at the first part.

Which fields should a supplier return record carry beyond the RMA number?

Condition evidence on receipt, a reason code from a versioned list, the remedy type with the units and value it covers, a disposition with who instructed it, and the approver of the authorization and any exception. Stage timestamps and links to the receipt, credit memo and payables match let each be checked.

Why grade an AI agent on completeness and not only on the authorization?

Because a correct authorization can still leave credits, stock and accountability wrong. An agent that approves the right returns but never closes condition, remedy basis or disposition creates work and errors downstream. Scoring completeness separately shows whether a new model is actually finishing returns.

Can free-text notes stand in for reason codes in a returns dataset?

Not on their own. Free text is valuable context, but it cannot be counted reliably across suppliers or years. Keep the original text beside a code from the list in force on the decision date, and record the code list version so later changes do not silently relabel old returns.

Who decides what happens to rejected goods sent back to a supplier?

Often the supplier. Under UCC section 2-603, a merchant buyer holding rightfully rejected goods, where the seller has no agent or place of business at the market, generally has to follow the seller's reasonable instructions, and contracts usually set disposition terms too. This is general information; counsel should review specific agreements.

Sources

  • X12's 180 transaction set, Return Merchandise Authorization and Notification, covers returning goods to a vendor and can be used to request, authorize or disposition a return or give notice of one. Source
  • UCC section 2-603 has a merchant buyer holding rightfully rejected goods, where the seller has no agent or place of business at the market, follow the seller's reasonable instructions. Source
  • UCC section 2-604 lets the buyer store, reship or resell rightfully rejected goods for the seller's account if no instructions arrive within a reasonable time. Source
  • 21 CFR 211.204 requires records of returned drug products including the reason for return, quantity returned, date of disposition and ultimate disposition, and destruction unless investigation proves quality. Source
  • FDA guidance describes the DSCSA requirement that a wholesale distributor verify the product identifier of a saleable returned product before further distribution. Source
  • Spree 6's returns migration creates a return with reason, created_by, status, memo and approved, received, refunded and canceled timestamps, and return lines with quantity, received quantity, pre-tax amount and a resellable flag defaulting to true. Source
  • Spree's actor migration lists created_by, approver and canceler for orders but only created_by for returns. Source
  • Spree's Return model says one record owns permission, physical receipt and money back, replacing the ReturnAuthorization, CustomerReturn and Reimbursement chain removed in 6.0. Source
  • Spree's returns documentation says arrival is not inspection and that receiving takes the quantities the warehouse counted, with only resellable goods going back into stock. Source
  • nopCommerce's ReturnRequest stores ReasonForReturn and RequestedAction as strings, an UploadedFileId, StaffNotes and a ReturnedQuantity described as the quantity returned to stock. Source
  • OpenCart's return table carries an opened flag and reason, action and status keys; its return_history table has no user column; the seeded actions are Waiting for return, Credit Issued, Replacement Sent and Refunded. Source
  • PrestaShop's order_return table stores a state and a free-text question; order_return_detail stores product quantity and a cancelled flag. Source
  • Open Source Point of Sale records a return to a supplier as a receiving in return mode, negating quantities in the Receivings controller; receivings carry supplier, employee, comment and reference. Source

Tell us what data you need

Share scope, volume, format, timing and licensing needs. Datasets are sourced on request.

See if your company qualifies