Skip to content

How to design Amazon Lockers

The first sections are free. The deep dives, level expectations and quiz are part of Pro.

On this page
Asked at
Practice this question

The problem

Amazon Lockers is a network of self-service pickup sites: when a package ships, the service claims a locker of the right size at the site the customer chose, the driver drops the parcel in, the customer opens the door with a code, and a parcel nobody collects goes back for return. The traffic is small, so the difficulty is correctness on a small, fixed stock. The answer turns on treating each locker as a row with a state, where the claim is a single update that both checks and takes the locker, and each later step moves the state forward from the state it expects.

Clarifying questions

AskWhy it mattersA typical answer

Who picks the site, and when is the locker claimed: at checkout or when the package ships?

If lockers were claimed at checkout they would sit reserved for days before the parcel exists, and the stock would run out. Claiming at ship time keeps the hold short, which shapes how long a reservation may live.

The customer chooses the site at checkout. The locker is claimed when the package ships to that site, and the customer gets the code when it is dropped off.

How long is a package held, and what happens when the deadline passes?

The hold length sets how fast lockers turn over, and the expiry rule decides whether you need a return path in the design.

A few days. Amazon's public page gives three calendar days, after which the item goes back and the customer is refunded. For this round: the package expires, the locker is emptied by a return pickup, and refunds are out of scope.

How big is the network, and how hard do orders compete for a locker?

Thousands of sites with tens of lockers each means a tiny data set and low request rates. The work is in two orders colliding on the last free locker, not in throughput.

Thousands of sites, tens of lockers at each, and at a busy site two orders can ask for the last large locker in the same second.

How does the customer open the door: a typed code, a barcode, the app?

A typed code is the simplest to design for and sets the security questions: how long, how random, how many tries. Barcodes and app flows are variations on the same check.

A pickup code for this round. In the real product the unit takes a six-digit code, and some sites use a barcode or the shopping app instead; treat those as alternate carriers of the same secret.

Must a site keep working when it loses its network link?

If yes, the unit at the site needs enough local knowledge to verify a code locally, and the design needs a way to reconcile what happened offline.

Yes, through a short outage: a valid code still opens its locker, and the events reach the service when the link returns.

If no locker of the parcel's size is free, may it go in a bigger one or to a nearby site?

This decides what the claim does when it finds nothing: fail the request, or widen the search. It also affects how often large lockers run out.

Your choice, and say it out loud. A good default: try a bigger locker at the same site first, then offer a nearby site, and keep large lockers for large parcels when stock is low.

The requirements menu

RequirementScopeWhy

Assign a free locker of the right size at the chosen site when a package ships there

Core

The write that the whole round turns on. Two shipments that reach for the same last locker must end up in different ones.

The driver opens the assigned locker and confirms the drop-off

Core

This is the moment the hold becomes a real parcel in a real locker, and it starts the customer's pickup clock.

The customer gets a pickup code and opens the locker with it

Core

The read path for people: a secret that opens one door once, verified at the site.

A package not picked up by its deadline expires and goes back for return

Core

Without it, lockers fill with forgotten parcels and the stock shrinks for good. It forces a scheduled job and a return flow.

Show the customer nearby sites that have room for a parcel of this size

Optional

Worth taking: it is the first API call and it is cheap, a count of free lockers per size and site. Say that it is advisory, since the real claim happens when the package ships.

Put the parcel in a bigger locker when its own size has run out

Optional

Take it if time allows: it is one more size in the claim's search order. Mention the cost, which is large lockers running out for large parcels.

Let someone else collect the parcel with a forwarded code

Optional

Falls out for free from a door check that asks for nothing but the code: whoever holds the code opens the locker. Name it, and name the risk it carries.

Remind the customer before the deadline

Optional

A second scheduled job on the same table as expiry. Take it if the interviewer wants more on notifications; otherwise park it.

Take out-of-service lockers out of the pool and bring them back after repair

Optional

One more state on the locker that the claim skips. Cheap to add, and it shows the state machine is complete.

Accept returns through the same lockers

Optional

A follow-up to prepare for: the customer becomes the one who drops off and a courier the one who collects. Keep it out of the first design and show how the same states cover it if asked.

Routing deliveries to the site

Out of scope

Which van carries the parcel is a logistics system of its own. The locker service learns about the parcel when it ships and when it arrives, nothing in between.

Payments and refunds for returns

Out of scope

Expiry hands the parcel to a return flow and stops there; money is another service's problem.

The locker hardware itself

Out of scope

Assume a unit at each site that can open a door and report that it opened and closed. The protocol between unit and service is in scope; the motor is not.

Barcode and app-based opening

Out of scope

Alternate carriers for the same secret. Design the typed code; the others reuse the verification.

Non-functional requirements

RequirementWhat it forces

One locker never holds two packages: assignment is strongly consistent

The claim is a single statement against the current row, run by the service that owns the lockers table in one primary database. No check-then-write across two calls, no cache in front of the claim, and no replica serving it.

Pickup codes are single use and hard to guess

Codes come from a cryptographic random source, are scoped to one site so a guess has few targets, are stored hashed with a secret kept outside the database, and are retired by the same state change that records the pickup. Entry attempts at a unit are rate-limited.

A site keeps opening lockers for valid codes through a short network outage

The unit at the site holds, for each of its occupied lockers, a verifier it can check on its own: the code hashed with a key the unit keeps, pushed by the service at drop-off. When the link is down it verifies locally and keeps a queue of door events to send later. Those late events carry ids so the service applies each once.

Estimates

QuantityWorkingResultWhat it sizes

Lockers in the network

Thousands of sites, say 5,000, times tens of lockers each, say 40: 5,000 × 40 = 200,000 lockers

About 200,000 locker rows

The lockers table: tiny, so one relational database holds the whole network and the question is contention, not capacity.

Assignments per day and per second

A locker turns over at most once in a few days, say 3: 200,000 ÷ 3 ≈ 67,000 assignments a day; 67,000 ÷ 86,400 seconds ≈ 0.8 a second; a peak day ten times the average ≈ 8 a second

Under 1 claim a second on average, single digits at a network-wide peak

Assignment load on the database: nowhere near a bottleneck, which is why the deep dive is about two requests on one row, not throughput.

Claims at the busiest site on a peak day

40 lockers that all turn over in a day = 40 successful claims; if ten times as many shipments ask, 400 requests a day, roughly one each 4 minutes

Hundreds of requests a day at the busiest site, spread thin

The hot spot: a few dozen rows at one site, where the risk is two claims in the same second, not a queue of thousands.

Storage for a year of assignments

67,000 assignments a day × 500 bytes ≈ 33.5 MB a day; × 365 days ≈ 12 GB a year; locker rows at 200 bytes × 200,000 = 40 MB

About 12 GB a year, plus a few tens of MB of locker state

The database: one primary with a standby, no partitioning needed for size. Partitioning by site, if ever, is for contention or isolation.

Guesses needed against a six-digit code

A six-digit code has 10^6 = 1,000,000 values. A site with 40 occupied lockers has 40 live codes, so one random guess hits with chance 40 ÷ 1,000,000 = 1 in 25,000; expected guesses to a hit = 25,000. At a limit of 5 attempts a minute per unit, that is 5,000 minutes ≈ 83 hours at the keypad

About 25,000 guesses on average, which a modest rate limit turns into days of standing at the unit

The rate limit on code entry, and why codes are scoped per site: a code valid network-wide would have thousands of times as many targets.

Core entities

EntityWhat it holds

Locker site

A physical location with a unit that controls a set of lockers.

Locker

One compartment: its size and its current state. The row the claim and each transition fight over.

Package

The parcel on its way to a site, with the size that decides which locker fits.

Assignment

The link between one package and one locker, holding the hashed pickup code and the clock that frees the locker.

Door event

A message from the unit saying a door opened or closed, kept so a repeated message is recognized.

Return pickup

Work for a courier to empty an expired locker.

The API

EndpointNotes

GET /sites?near=&size= → sites with free lockers of that size

A read of free-locker counts per site and size, from the lockers table or a per-site count refreshed often. It is advisory: a site listed as free may be full by the time the package ships, and the real decision is the claim below. In the real product a customer sees and picks from sites that have room at that moment.

POST /assignments { package_id, site_id, size } → { locker_id, expires_at }

The claim. One update flips a free locker of that size at that site into reserved and returns its id; expires_at is the reservation deadline the driver must beat. Idempotent on package_id: a retry gets the same locker back. When nothing is free, respond 409 Conflict with the bigger size or nearby sites that have room, so the caller can choose.

POST /lockers/{id}/drop-off { package_id } (driver) → door opens

Checks that this locker is reserved for this package, asks the unit to open the door, and moves the locker to occupied when the unit reports the door closed. The pickup deadline is set here, and the pickup code is sent to the customer here, not at claim time, so a late delivery does not start the customer's clock early.

POST /sites/{id}/pickup { code } → door opens

Hashes the code with each live salt at this site and compares against the occupied assignments there; a match opens that locker and the same transition retires the code. Attempts are rate-limited per site, and a wrong code gets a plain failure with no hint. During an outage the unit runs its own check against the local verifiers it received at drop-off.

The high-level design

drop-offassigneventsclaimDriver appSite unitOrder serviceLocker serviceLockers DB

Step 1 of 4

Claim, drop off, open

Start with the parcel's path. The order service tells the locker service that a package is shipping to a site. The locker service owns one relational table of lockers (about 200,000 rows for the whole network) and a table of assignments, and it claims a locker with one update that both checks the row is free and marks it reserved. At the site, a unit holds the doors: the driver's app asks the service to open the reserved locker, the unit opens it, and reports the door closed, which moves the locker to occupied. The service and the unit talk over a persistent connection, so a command and its confirmation are messages, not polling.

drop-offcodeassigneventschecksclaimcodeoverduescheduleDriver appSite unitCustomerOrder serviceLocker serviceHashed codesLockers DBNotificationExpiry jobReturn pickup
The whole design

What breaks first

The deep dives

Assigning lockers under contention. Two shipments ask for the last large locker at one site within the same second. Walk through what the locker service does so they end up in different lockers, or one of them is told there is none, and what happens to the hold if the delivery does not show up.

A concept that helps here: Optimistic and pessimistic lockingA concept that helps here: Transactions and isolation levels

Locker states and expiry. Take one locker from free back to free. Name each state, the event that moves it on, and what the service does when two events hit the same locker in the same second, when a door confirmation is sent twice, and when the pickup deadline passes as the customer types the code.

A concept that helps here: Idempotency keysA concept that helps here: Job scheduling and delayed work

Concepts this guide uses

Sources

  1. PostgreSQL documentation: Transaction Isolation
  2. PostgreSQL documentation: Explicit Locking
  3. Amazon DynamoDB developer guide: Working with items and attributes (conditional writes)
  4. Amazon Builders' Library: Making retries safe with idempotent APIs
  5. About Amazon: How to use Amazon Locker
Sign in to report a mistake