DEV Community: Maruf

One item per row: designing bulk order creation

Maruf — Sat, 24 Oct 2026 14:07:04 +0000

A merchant who ships forty parcels a day doesn't want to fill in a form forty times. Most of them already keep those orders somewhere else, in a spreadsheet or an export from the store they sell on. What they need is a way to bring a day's orders in at once, fix whatever is wrong before anything is created, and never end up with the same order twice.

That's the whole brief for bulk order creation. The interesting part is that the first design decision, what one row means, shapes everything after it.

Diagram: the first plan put one order on a row and hid its items in a drawer. the shipped sheet puts one item on a row, the way the file already does, and sends the orders in one bulk request. See it on maruf.ing

the need behind it

Three things matter to the merchant, in this order:

Getting the orders in. Most of them arrive as a CSV, not typed by hand. If the import is fussy, people give up and go back to the one-by-one form.
Fixing problems before anything is created. A wrong city or a missing phone number should be caught on the sheet, not discovered after a parcel is booked.
No duplicates. Creating forty orders is a batch. If the network drops halfway, retrying must not create the first twenty again.

Every decision below is in service of one of these.

first approach: one order per row

My first sketch put one order on each row. Recipient name, phone and address on the left, then a products cell showing a summary like "2 items". Clicking it opened a side drawer with the same product and variant picker the single-order screen uses.

It looked tidy. An order is the thing the merchant is creating, so one row per order felt right.

The problem showed up as soon as I thought about the import. The files merchants already have put one item on each row, with the order reference repeated for a multi-item order. That's how most store and shipping exports work, Shopify's included. A sheet shaped differently from the file turns every import into a translation step, and every error points at a cell that doesn't exist in the merchant's own spreadsheet.

So I dropped it.

second approach: one item per row

The sheet now has the same shape as the file:

one row is one line item
adjacent rows with the same order reference are one order
a row with a blank order reference is its own single-item order
the same reference on rows that aren't next to each other is an error, not a silent merge

order ref	name	phone	city	sku	qty
A-101	Rahim	017…	Dhaka	TSHIRT-L	1
A-102	Karim	018…	Dhaka	MOUSE-01	1
A-102				CABLE-1M	2

This also lines up with the backend. Each group of rows becomes exactly the payload the single-order form already sends, so the server doesn't need a second idea of what an order is.

The drawback is readability. Once an order spans rows, it's easy to lose track of where one ends and the next begins, and recipient details repeated on every row look like separate orders.

The fix:

Order-level cells (recipient, address, amount to collect) show only on an order's first row. The rows below stay empty, so a total never looks like it's charged twice. The order reference repeats in a muted color as the group marker.
A bracket in the row-number column marks each multi-item order, inset at both ends so two neighbouring orders stay visibly separate. Dividers are dashed inside an order and solid between orders.
No merged cells. rowSpan looks like the natural tool, but inserting rows, keeping row keys stable and sorting all get harder once cells span rows.

an import that doesn't give up

A strict importer is easy to build and miserable to use: one unexpected column header and the whole file is rejected. Since getting orders in is the first need, the import here never refuses a file. It loads what it can and marks the rest on the sheet.

Headers are matched ignoring case, spaces and punctuation, so Phone, phone and Phone (*) all land in the same column. Columns the sheet doesn't know are ignored.
Common aliases map to the same field. A product can arrive as sku or as a free-text item name, a pickup point as pickup location or store, so files exported from different tools load without editing.
Unknown products become custom line items named after the text. An item that isn't in the catalogue yet is still a real parcel, so it's not a reason to reject the order.
Locations are matched against the real list. An exact match is fine. A close match ("banani dohs" for "Banani Old DOHS") is filled in and marked yellow for review. No match is red. When the city or zone is missing, an address parser fills it in from the street address, also yellow.
Unknown pickup locations fall back to the merchant's default one, marked yellow until someone picks.

The sheet after an import: A-102 is one order across two rows, a best-guess zone in yellow, a phone to fix in red, and an unknown product kept as a custom item. confirm stays off until the red cell is fixed.

tip: Red blocks the submit, yellow doesn't. A "go to error" button jumps to the top-most, left-most red cell, so fixing a file walks it in reading order.

submitting the batch

Once the sheet is clean, the orders go to the server in one request. The obvious shortcut, looping over the single-order endpoint, is slow for big batches and falls apart on exactly the third need: a request that times out after the server already created the order looks like a failure, and a retry creates a duplicate.

So the batch gets its own endpoint, built on the same rules as the single one:

POST /orders/bulk

{
  "orders": [
    { "idempotency_key": "A-101", "order": { ...the single-order payload... } },
    { "idempotency_key": "A-102", "order": { ...the single-order payload... } }
  ]
}

HTTP/1.1 200 OK

{
  "results": [
    { "idempotency_key": "A-101", "status": "created", "order_id": "ord_8f2k" },
    { "idempotency_key": "A-102", "status": "failed",
      "errors": { "pickup_location": "this location is inactive" } }
  ]
}

Each element is the exact single-order payload, and the server runs the same create logic for each one. There's one definition of a valid order, not two.
Results are per order. One bad order doesn't fail the batch. The response says which ones were created and which failed, and why.
Each order carries an idempotency key, built from the merchant's order reference. If the same key comes back, the server returns the order it already created instead of making a new one, so a retry after a timeout is safe. Two guards make that hold up:
- Scope the key and fingerprint the payload. Merchants restart their numbering, so a fresh sheet can start at A-101 again. Store the key per merchant, together with a hash of the order payload. Same key and same payload returns the existing order. Same key with a different payload is a 409 Conflict, never a silent return of last week's order. Letting keys expire after a day or so also fits how sheets are used.
- Only a created order claims the key. Write the key in the same transaction that creates the order. If a failed attempt stored it, the fixed resubmit below would get the old failure back.
Field errors map back to cells. pickup_location in the response turns that cell red on the sheet, with the server's message.

On the sheet, created orders lock and failed ones stay editable, so the merchant fixes only what failed and submits again. The keys make that second submit harmless for the orders that already went through.

keeping the sheet fast

A spreadsheet that lags while you type is worse than a form. The first version re-rendered every cell on every keystroke: fine with ten orders, sluggish with sixty. Two changes fixed it. Cells type into local state and commit to the sheet on a short pause or on blur, and rows are memoized so an edit only re-renders the row it touched. Validation and the address parser then run per committed value, not per key.

what it costs

Order fields live on the first row. To change a recipient you edit the order's first row, not any row. That's the price of matching the file.
Big orders get tall. A forty-item wholesale order is forty rows. For a tool aimed at many small orders, that's acceptable.
Partial success needs a UI. Per-order results are more honest than all-or-nothing, but the sheet has to show a status on every order and make "fix and resubmit" obvious.

the lesson

I started by designing the sheet around ~~what an order is~~ what the file looks like. When most of the data arrives as a file, the file's shape is the interface. The database, the API and the validation can all adapt to it, and here they barely had to.

First published on maruf.ing. I write about boring backend systems.

Patch the image, not the version

Maruf — Sat, 24 Oct 2026 11:30:37 +0000

October 21 was a busy day for anyone who runs servers. PHP fixed two critical remote code execution bugs. GitLab fixed one rated 10.0. Node.js shipped security releases for its 22, 24 and 26 lines, including an out-of-bounds write in the Brotli decoder that the advisory says can lead to remote code execution.

Different stacks, same job: patch it, then prove the patch is running.

The Node one looked like a one-line change:

- FROM node:22.12.0-alpine
+ FROM node:22.23.4-alpine

Bump the number, rebuild, deploy. I did this on a set of containerized services that week, and the version bump was the easiest part. The real work was finding every place the version lived, noticing what else the new image changed, and checking which pods actually picked it up.

Diagram of the whole trip (① pick the patch, ② change every pin, ③ the image moves its OS packages too, ④ only rebuilt services get the fix, ⑤ deployed isn't running, so check the pods): see it on maruf.ing

1. Patch now, upgrade later

The advisory lists a fixed version per line: 22.23.4 for 22.x, 24.22.1 for 24.x. Both carry the same security fixes, so the only question is how much else you want to change today.

	stay on 22	move to 24
Change	patch only	major
Risk	low	APIs, native modules, deps
Support ends	Apr 30, 2027	Apr 30, 2028

I took the 22 patch. A security fix should ship fast, and if it rides along with a major upgrade, a failure could come from either change. The move to 24 is real work (native modules rebuild, deprecated APIs, dependency ranges) and gets its own change and its own testing.

That doesn't make 24 optional. Node 22 has about six months of support left, so the patch buys time to do the upgrade properly, not a reason to skip it. And if your line is already end of life, the order flips: there is no patch to take.

2. Find every pin

"Which Node do we run?" usually has several answers in one repository:

the FROM lines in each Dockerfile, often two per file in a multi-stage build
the image the CI jobs build and test in
engines in package.json, .nvmrc, .tool-versions
dev containers and local compose files

These drift. A new service gets copied from an old template and keeps its old tag. CI tests on one version while production runs another. A fix applied to "the version" lands in some of these places and quietly misses the rest.

So the first step is a search, not an edit:

# find-pins.sh
# Every place a Node version might be pinned.
# Review each hit; not every match is a runtime pin.
grep -rnE 'node:[0-9]|"node":|nodejs' \
  --include='Dockerfile*' --include='*.y*ml' \
  --include='package.json' --include='.nvmrc' \
  --include='.tool-versions' .

One hit to leave alone: @types/node has its own version numbers and isn't the runtime.

The longer fix is fewer pins. One build argument every Dockerfile reads, and CI and local tooling reading the same file. Then the next advisory is one edit.

3. The image is part of the change

This was the part that surprised me.

A tag like node:22.23.4-alpine doesn't say which Alpine it's built on. It means whatever Alpine the maintainers build on today. The image I was replacing was built on an older one, so the new tag moved Alpine forward two releases.

Each Alpine release ships its own versions of every system package. Anything your service installs with apk add moves with it. For me that was ffmpeg, which one service uses to process uploaded media: 6.1 on Alpine 3.21, 8.0 on 3.23. A Node security patch had become a major upgrade of a media tool, and nothing in the diff said ffmpeg.

Yours might be ImageMagick, libvips, a Postgres client, git, fonts or the CA certificates. Same thing: the tag you bumped says Node, and something else moved.

A container image is a stack: base OS, system packages, runtime, your dependencies, your code. Changing the tag can move any layer under it. Call it base-image drift.

# Dockerfile
# Floating base: Alpine moves when this tag is rebuilt.
FROM node:22.23.4-alpine

# Explicit base: only Node moves.
FROM node:22.23.4-alpine3.23

Naming the Alpine release makes the change visible in review. It doesn't always let you keep the old base, since new Node patches are only published for the Alpine releases still being built on. When the old one isn't offered, the base move is part of the patch, and you test it that way. Debian tags like -bookworm already name the release, so the OS stays put across Node patches, though its packages still pick up updates on rebuild.

Either way, before shipping, compare the system packages your service actually uses in the old and new image. apk info -v (Alpine) or dpkg -l (Debian) in each is a quick diff.

careful: A major bump in a system tool can pass a smoke test and still behave differently: new defaults, removed flags, slower output. Running the service's exact command in a test container only proves the command runs. Push real input through it on staging (an upload, an import, a report) and compare the result.

4. Green isn't proof

Two things can make a successful pipeline lie to you.

Path filters. Many pipelines rebuild only the services whose files changed. A service you didn't touch keeps its old image and its old Node. If a service gets its runtime from a shared base image instead of its own FROM line, the filter won't see that it needs a rebuild. Touch every affected service or force a full rebuild.

"Deployed." With Helm, STATUS: deployed means the manifests were applied and the release was recorded. Without --wait, it says nothing about whether new pods started, passed readiness, or replaced the old ones. A pod stuck on a bad image sits behind a release that says deployed.

So check what is actually running:

# check-rollout.sh
# Did the rollout finish, and which image runs?
kubectl rollout status deploy/api --timeout=5m
kubectl get pods -l app=api \
  -o jsonpath='{.items[*].spec.containers[*].image}'
# The runtime itself, from inside a live pod.
kubectl exec deploy/api -- node --version

The first waits for the rollout. The second shows the image the pods started from. The third answers the original question from inside a running container. Do it for every affected service, not one sample.

In my case the deploy log showed every release upgraded, but my cluster login had expired, so for a while that log was all I had. After logging back in I checked the pods, and they were running the patched version. Only then was it done. A deploy log is evidence that a deploy happened, not that the fix is running.

5. Make the pipeline check it

Checking every service by hand is tedious, which is a good sign it belongs in the pipeline:

rebuild everything that depends on a shared base image when that image changes
deploy with --wait and a timeout, so the pipeline fails when pods don't come up
after rollout, read the runtime version from a pod and compare it to the expected one

For one service with no system packages, most of this collapses into bump, deploy, check. The list grows with the number of places the version lives and the number of things the image carries besides Node.

The short version

The advisory gives you a version number. It doesn't tell you where that number lives, what else moves with the image, or which pods picked it up.

The version bump is one line. Proving it reached production is the work.

First published on maruf.ing. I write about boring backend systems.