E-commerce
A returns portal for an online shop
A customer starts a return from their order, picks a reason, and prints a label. The warehouse scans it in and the refund is issued automatically if the item passes inspection. The shop sees which products are returned most and why.
Automatically generated draft
Written by machine against our own engineering playbook. The company is invented; the decisions are the ones we would make on a real build. A reviewed blueprint goes further — nine sections, agreed line by line, and it is what the build is tested against.
Section 01 · What has to work
Customers must be able to initiate a return, print a valid shipping label, and receive an automated refund upon warehouse inspection.
Section 03 · Screens
Every screen, and what it is for.
- ›Order Lookup — Customer enters order ID and email to view returnable items. Instant search.
- ›Return Form — Customer selects items, picks return reasons, and submits. Instant reason population.
- ›Label View — Customer views and triggers PDF print of the generated carrier return label. Instant render.
- ›Warehouse Scanner — Warehouse staff scans incoming return barcode to load inspection details. Instant lookup.
- ›Inspection Grade — Staff marks item pass/fail and triggers refund logic. Instant submission.
- ›Analytics Dashboard — Shop owner views return rates by product and reason code. Instant aggregations.
Anything not on this list is not in version one. That is what keeps a fixed price fixed.
Section 04 · The data model
What it stores, and who can read a row.
return_request
id uuid, order_id text, customer_email text, status enum(requested,labeled,received,inspected,refunded,rejected), created_at timestamptz
Access · Customers read own rows via email match; warehouse and shop read all.
return_item
id uuid, return_id uuid, sku text, reason_code text, inspection_result enum(pending,passed,failed), restockable boolean
Access · Customers read items on their return; warehouse and shop read all.
return_label
id uuid, return_id uuid, tracking_number text, carrier text, label_url text, generated_at timestamptz
Access · Customers read labels for their returns; warehouse and shop read all.
Those access rules belong in the database, not in the screens. Someone who edits the address bar still cannot read a row that is not theirs — and the test that proves it blocks delivery if it fails.
Section 05 · States
requested → labeled → received → inspected → refunded | rejected
Most scope arguments three weeks into a build are really arguments about a state nobody named at the start.
Section 06 · Where this breaks
What bites products like this one.
Carrier API goes down when generating labels, blocking customers from completing return requests.
Queue label generation asynchronously and allow fallback to pre-generated generic return labels.
Warehouse scans a damaged barcode or incorrect item, causing mismatched inspection states.
Strictly validate scanned barcode against expected return_item SKUs before allowing inspection entry.
Section 08 · Deliberately left out
What version one does not do.
- ×Automated carrier pickup scheduling — High third-party integration overhead; makes sense for v2 once volume justifies it.
- ×Self-service exchange for a different size — Adds complex inventory hold logic; v1 handles refunds only.
This is the section that protects the date, and the only place in the document where somebody says no. It is also why clients trust the rest of it.
Still open
What we would ask before quoting.
- Which e-commerce platform hosts the orders, and do we have API webhook access for order status updates?
- Which shipping carrier API are we using to generate and purchase return labels?
- What payment gateway processes the original orders, and do we have permissions to issue automated refunds?
Half of this already exists
Doc Intake
The paperwork half of this is a solved problem: documents read on arrival, validated against your rules, and a person asked only about what does not add up.
It is one of our pre-built products: the code is handed over to you, adapted to your own wording and rules, and the rest of the specification above is built on top of it rather than from scratch.
Your product, not this one
Get this written for what you are actually building.
Describe it in a sentence and the generator returns the same sections for your own product. Free, no email, nothing saved to a list.
Next step
Find out if your idea fits in 10 working days.
Tell us what you want to build. We reply the same day with a straight yes, no, or here is what we would cut.