Nov 17, 20266 min read

Warehouse Receiving Backend: ASNs, Dock Check-In and Putaway Events

Record an advanced shipping notice, check a shipment in at the dock, count it, and publish putaway events that inventory and billing can both consume.

Illustration for Warehouse Receiving Backend: ASNs, Dock Check-In and Putaway Events

Warehouse receiving starts before the truck arrives: the supplier sends an advanced shipping notice (ASN), the dock team checks the shipment in, someone counts the lines, and inventory cannot move until a putaway event says where the stock now lives.

The usual bugs are a second check-in for the same trailer, a count that does not match the ASN, and a putaway event that is published twice. This guide designs a backend around an ASN, a receipt with an idempotency key, counted lines and a putaway topic, then builds it in Go with Encore in your own AWS or GCP account.

Quiqup built a logistics platform connecting order sources, fulfillment centers and delivery partners, using Encore, and Pallet built an event-driven logistics platform on GCP with Encore. Those are nearby logistics cases, not a claim that either product is this exact receiving flow.

Receiving at a glance

StepWhat is recordedGuard
ASN receivedShipment id, expected time, expected linesUnique ASN id
Dock check-inDoor, arrival time, carrierUnique (ASN, door, arrival date) so a retry is the same receipt
CountActual quantity per SKU, variance against the ASNCount only on a checked-in receipt
PutawayLocation and quantity per counted lineEvent published after the line is committed, idempotent on line id

ASNs, receipts and variance

Store the ASN as a header plus expected lines, then check-in creates a receipts row with a unique key; a network retry must return that row, not a second receipt. Counting writes receipt_lines with expected_qty and actual_qty. A variance does not have to block putaway, but it should be visible, and some warehouses will hold the line until a supervisor acknowledges it.

Putaway is an event, not only a column, because inventory and billing usually live in other services. Publish after the line is committed, and let subscribers claim the line id before they increment on-hand stock.

How do you build this with Encore?

Encore

Encore is a backend framework with built-in infrastructure. You declare the database and a topic in the same package as the handlers, and encore run starts local Postgres so you can post an ASN, check it in and count it before opening a pull request. On deploy to your own AWS or GCP account, Encore provisions those resources and Encore provisions an IAM role for the service, or a service account on GCP.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

-- receiving/migrations/1_receiving.up.sql CREATE TABLE asns ( id TEXT PRIMARY KEY, supplier_id TEXT NOT NULL, expected_at TIMESTAMPTZ NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now() ); CREATE TABLE asn_lines ( asn_id TEXT NOT NULL REFERENCES asns (id), sku TEXT NOT NULL, expected_qty INT NOT NULL CHECK (expected_qty > 0), PRIMARY KEY (asn_id, sku) ); CREATE TABLE receipts ( id TEXT PRIMARY KEY, asn_id TEXT NOT NULL REFERENCES asns (id), door TEXT NOT NULL, arrived_on DATE NOT NULL, arrived_at TIMESTAMPTZ NOT NULL, UNIQUE (asn_id, door, arrived_on) ); CREATE TABLE receipt_lines ( id TEXT PRIMARY KEY, receipt_id TEXT NOT NULL REFERENCES receipts (id), sku TEXT NOT NULL, expected_qty INT NOT NULL, actual_qty INT NOT NULL, location TEXT, UNIQUE (receipt_id, sku) ); CREATE TABLE applied_putaways ( line_id TEXT PRIMARY KEY, applied_at TIMESTAMPTZ NOT NULL DEFAULT now() );
// receiving/receiving.go package receiving import ( "context" "time" "encore.dev/pubsub" "encore.dev/storage/sqldb" ) var db = sqldb.NewDatabase("receiving", sqldb.DatabaseConfig{Migrations: "./migrations"}) type Putaway struct { LineID string `json:"line_id"` SKU string `json:"sku"` Qty int `json:"qty"` Location string `json:"location"` } var Putaways = pubsub.NewTopic[*Putaway]("putaway", pubsub.TopicConfig{ DeliveryGuarantee: pubsub.AtLeastOnce, }) type CheckInIn struct { Door string `json:"door"` } type CheckInOut struct { ReceiptID string `json:"receipt_id"` } //encore:api public method=POST path=/asns/:id/check-in func CheckIn(ctx context.Context, id string, in CheckInIn) (*CheckInOut, error) { receiptID := id + ":" + in.Door + ":" + time.Now().UTC().Format("2006-01-02") _, err := db.Exec(ctx, ` INSERT INTO receipts (id, asn_id, door, arrived_on, arrived_at) VALUES ($1, $2, $3, DATE(now()), now()) ON CONFLICT (asn_id, door, arrived_on) DO NOTHING`, receiptID, id, in.Door) if err != nil { return nil, err } return &CheckInOut{ReceiptID: receiptID}, nil } type CountIn struct { SKU string `json:"sku"` Actual int `json:"actual_qty"` Location string `json:"location"` } //encore:api public method=POST path=/receipts/:id/lines func CountLine(ctx context.Context, id string, in CountIn) error { var expected int err := db.QueryRow(ctx, ` SELECT expected_qty FROM asn_lines WHERE asn_id = (SELECT asn_id FROM receipts WHERE id = $1) AND sku = $2`, id, in.SKU).Scan(&expected) if err != nil { return err } lineID := id + ":" + in.SKU _, err = db.Exec(ctx, ` INSERT INTO receipt_lines (id, receipt_id, sku, expected_qty, actual_qty, location) VALUES ($1, $2, $3, $4, $5, $6) ON CONFLICT (receipt_id, sku) DO UPDATE SET actual_qty = EXCLUDED.actual_qty, location = EXCLUDED.location`, lineID, id, in.SKU, expected, in.Actual, in.Location) if err != nil { return err } _, err = Putaways.Publish(ctx, &Putaway{LineID: lineID, SKU: in.SKU, Qty: in.Actual, Location: in.Location}) return err } var _ = pubsub.NewSubscription(Putaways, "update-on-hand", pubsub.SubscriptionConfig[*Putaway]{ Handler: func(ctx context.Context, ev *Putaway) error { res, err := db.Exec(ctx, ` INSERT INTO applied_putaways (line_id) VALUES ($1) ON CONFLICT (line_id) DO NOTHING`, ev.LineID) if err != nil || res.RowsAffected() == 0 { return err // already applied } // Increment on-hand stock for ev.SKU at ev.Location by ev.Qty here. return nil }, }, )

The subscriber should use a unique applied_putaways table (add it to the migration) and only increment on-hand stock when the insert succeeds. This flow sits upstream of proof of delivery and shipment tracking.

Best fit: a warehouse that wants ASN check-in, counts and putaway events in one service.

Receipts and putaway events by hand

Store the ASN as a header plus expected lines, and create a receipt with a unique key so a retried check-in returns the existing row. After a count, publish a putaway event to SQS or Pub/Sub, and have the subscriber insert the line id into an applied_putaways table before it increments on-hand stock. If the insert finds a conflict, skip the increment. The unique receipt key and the unique line id are the same guards you would use on a hand-built RDS and SQS setup.

How to choose

Use Encore when you want the ASN tables and the putaway topic declared in one Go service, with local Postgres and delivery under encore run. Use a hand-built RDS and SQS design when those resources already live in Terraform. In both cases, the unique receipt key and the unique line id on the subscriber are what stop double check-ins and double stock increments.

Frequently asked questions

What is an ASN in warehouse receiving?

An advanced shipping notice is the supplier's list of what is supposed to arrive: shipment id, expected dock time, and lines with SKU and quantity. The receiving backend stores that notice before the truck arrives, then records what was checked in and counted.

How do I keep a double check-in from creating two receipts?

Give the check-in an idempotency key, such as the ASN id plus the dock door and the arrival date, and insert the receipt with a unique constraint on that key. A retry of the same check-in returns the existing receipt instead of opening a second one.

When should putaway events be published?

Publish after a counted line is written in the same transaction as the count, including the location the stock was placed into. Subscribers update on-hand inventory or notify billing. The event should be idempotent on the receipt line id so a redelivery does not double the stock.

How do I build this with Encore?

Declare a Postgres database and a Pub/Sub topic in Go. encore run starts Postgres locally and delivers putaway messages to subscribers on your laptop. On deploy, Encore provisions RDS or Cloud SQL and SNS/SQS or GCP Pub/Sub in your own account.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders