When you check a coat at a theater, you don't carry the coat to your seat — you hand it over and get a little numbered tag. The tag is tiny and easy to pass around; the bulky coat sits safely in the cloakroom until you redeem the tag on your way out. The Claim Check pattern does exactly this for messages: keep the heavy thing in storage, pass around the lightweight ticket.
The problem
Message brokers love small messages. But real workloads often need to move large payloads — a 20 MB scanned document, a video to transcode, a fat batch of records. Stuffing those into a queue or topic causes real pain: many brokers enforce a maximum message size (Azure Service Bus and SQS are measured in hundreds of kilobytes, not megabytes), big messages slow the broker down and bloat memory, and you pay to shuttle the same large bytes through the messaging layer even when most consumers only need part of it. The messaging system was built to coordinate, not to be a file transfer pipe.
ProducerStuffs the entire large payload — a scanned doc, a video — directly into the message it puts on the queue.
QueueForced to carry megabytes it was never built for: it slows down, bloats memory, and may reject the message for exceeding the size limit.- WorkerMust wait for the whole heavy payload to crawl through the broker before it can even start.
How it works
Split the payload from the message. When the producer has a large payload, it first writes the payload to shared storage — a blob store, object store, or similar — which hands back a key or URL. The producer then puts only that reference (plus any small metadata) onto the queue. That reference is the claim check. The consumer pulls the small message, reads the reference, and fetches the full payload from storage only when it's ready to process it. The broker never touches the heavy bytes; it just carries the ticket. The diagram below shows the payload going into the store while a slim message — holding only the reference — flows through the queue to the worker, which redeems it for the real data.
- ProducerWrites the large payload to storage, then puts only a small reference on the queue.
Blob StoreHolds the heavy payload. The messaging system never touches these bytes.- Queue (ref)Carries only the lightweight reference — the 'claim check' — plus small metadata.
- WorkerReads the reference off the queue, then fetches the full payload from the store when ready.
Plan the payload's lifecycle. A claim check is useless if the coat has been thrown out — and dangerous if anyone can grab any coat. Give stored payloads a retention or cleanup policy so storage doesn't grow forever, and lock down access (signed URLs, scoped permissions) so only the intended consumer can redeem the reference.
When to use it
Reach for Claim Check whenever messages would otherwise carry large or variable-size payloads, especially if you risk hitting broker size limits or you want to keep queue-based load leveling snappy and cheap. It pairs naturally with pub/sub fan-out — many subscribers can share one stored payload via the reference — and with competing consumers pulling work off the queue. The stored payload can even act like a cache others reuse.
Skip it when payloads are already tiny: the extra storage round-trip and cleanup logic aren't worth it for a few hundred bytes. Claim Check earns its keep precisely when the thing you're moving is too big to comfortably mail.