The Queue

What This Does

After an order qualifies, it's dropped into an AWS SQS FIFO queue — think of it as a single-file waiting line. The queue ensures orders are processed one at a time per merchant, prevents duplicates, and decouples the webhook handler (fast, returns immediately) from the actual processing (slow, talks to ShipStation API).

Why It Matters

Without a queue, the webhook handler would have to do all the processing synchronously — and Shopify expects webhook responses within 5 seconds. The actual processing (fetching from Shopify, calling ShipStation, verifying) can take 30+ seconds. The queue lets the webhook return instantly while processing happens in the background.

How It Works

1. 1.An order is enqueued with a message body containing: shopId, shopifyOrderId, shopifyOrderNumber, timestamp, and optionally an 'approved' flag.
2. 2.MessageGroupId is set to the shopId — this means SQS processes orders for each merchant in sequence (FIFO = First In, First Out). Two orders from the same merchant won't process simultaneously.
3. 3.MessageDeduplicationId is set to the shopifyOrderId — this prevents the same order from being enqueued twice within the deduplication window (5 minutes).
4. 4.For approved re-enqueue (from the review queue), '-approved' is appended to the dedup ID so it doesn't collide with the original message.
5. 5.A Lambda function (the 'worker') polls the queue and processes each message.

Key Decisions

• ●FIFO queue (not standard) because order matters and we need deduplication. We can't have two workers processing the same merchant's orders simultaneously — they'd both read the same ShipStation data and conflict.
• ●MessageGroupId = shopId serializes per-merchant. This is critical because ShipStation's rate limits are per-account, and we need to honor them.
• ●The dedup ID scheme prevents the same order from being processed twice, but still allows re-enqueue after approval or retry.

What Could Go Wrong

• ●If SQS is down (extremely rare for AWS), orders would fail to enqueue. The webhook handler catches this and logs the error — the order stays in PENDING status and can be retried later.
• ●If the dedup ID collision prevented a legitimate re-enqueue, we'd miss processing an order. The '-approved' and '-retry' suffixes prevent this.