How to design Amazon Lockers
The first sections are free. The deep dives, level expectations and quiz are part of Pro.
On this page
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
| Ask | Why it matters | A 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. |
Non-functional requirements
| Requirement | What 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
| Quantity | Working | Result | What 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
| Entity | What 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
| Endpoint | Notes |
|---|---|
| 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. |
| The claim. One update flips a free locker of that size at that site into reserved and returns its id; |
| 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. |
| 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
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.
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: Atomic read-modify-write
A concept that helps here: Optimistic and pessimistic lockingA concept that helps here: Transactions and isolation levelsLocker 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: State machines in database rows
A concept that helps here: Idempotency keysA concept that helps here: Job scheduling and delayed workConcepts this guide uses
- Atomic read-modify-write
- Optimistic and pessimistic locking
- Transactions and isolation levels
- State machines in database rows
- Idempotency keys
- Job scheduling and delayed work