Claim Check Pattern

At a fancy restaurant, you don't carry your heavy winter coat to the table. You hand it to the coat check attendant, receive a small ticket with a number, and carry the lightweight ticket. When you leave, you present the ticket and get your coat back.

The claim check pattern works the same way for messages. Instead of stuffing a 50MB file into a message (which most brokers reject or handle poorly), you store the file in external storage (S3, blob storage) and send a lightweight message containing just a reference, a URL or storage key.

Message brokers are designed for small, fast messages, typically kilobytes. When you push megabytes through them, you get slow throughput, high memory usage, broker instability, and often hard rejections. SQS limits messages to 256KB. Kafka's default is 1MB. RabbitMQ slows dramatically with large messages.

The claim check pattern keeps your messaging system lean while supporting arbitrarily large payloads. The message stays small and fast; the payload lives in storage designed for large data.

Producer side (check in):

// 1. Store the large payload in blob storage
const payloadKey = `uploads/${orderId}/invoice.pdf`;
await s3.putObject(bucket, payloadKey, largePayload);

// 2. Send a lightweight message with just the reference
await queue.publish('invoice-processing', {
 orderId: 'order-123',
 payloadRef: {
 storage: 's3',
 bucket: 'my-bucket',
 key: payloadKey
 }
});

Consumer side (claim):

async function processInvoice(msg) {
 // 1. Retrieve the payload using the reference
 const payload = await s3.getObject(msg.payloadRef.bucket, msg.payloadRef.key);
 
 // 2. Process the full payload
 await processInvoiceData(payload);
 
 // 3. Optionally clean up the stored payload
 // await s3.deleteObject(msg.payloadRef.bucket, msg.payloadRef.key);
}

What to store externally:

• Files (PDFs, images, CSV exports, log bundles)
• Large API responses
• Batch data (thousands of records that would exceed message size limits)
• Binary data (serialized objects, protobuf payloads > 1MB)

What to keep in the message:

• The storage reference (bucket + key, or a presigned URL)
• Metadata needed for routing (event type, priority, content type)
• Enough context to decide whether to retrieve the payload at all