Quantity Verification

ShipHero's fulfillment webhook intermittently reports quantity: 1 for line items that actually shipped more (for example, one unit on a three-unit line). Trusting that number would understate what shipped. To guard against it, the worker re-checks each order's true line-item quantities against the ShipHero API before writing them.

How it works

The check runs once per webhook, right after the brand and warehouse lookups and before any line items are written.

1. buildVerifiedQuantities decides whether to verify. It returns null (meaning "just use the webhook values") if verification is disabled or the brand has no ShipHero access token.
2. fetchShipheroLineItemQuantities runs a GraphQL query against https://public-api.shiphero.com/graphql for the order's line items, building a map of legacy_id → quantity. The request has a 3-second timeout (AbortSignal.timeout).
3. resolveQuantity is called for each line item as it is written. It compares the webhook quantity with the verified one:
   • If there is no verified value, or the two match, it uses the webhook value.
   • If they differ, it uses the ShipHero value and logs a 🚨 Quantity mismatch warning naming the line item, SKU, and both numbers.

The resolved number is what lands in SKU_Quantity on the Shipment Line Items row.

Fail-open by design

Verification is a safety net, not a hard dependency. Every failure path (the feature being disabled, a missing token, a timeout, a throttle, a GraphQL error, or the order not being found) returns null, and the worker falls back to the webhook's own quantities. A slow or unavailable ShipHero API can never block a shipment from being recorded.

The kill switch

Verification is controlled by the optional VERIFY_QUANTITIES environment variable:

• Unset or any value other than "false" → verification is on (the default).
• "false" → verification is off; the worker uses webhook quantities and logs ℹ️ Quantity verification disabled via VERIFY_QUANTITIES.

Set it as a Cloudflare Worker secret to toggle the behavior without a code change:

npx wrangler secret put VERIFY_QUANTITIES
# enter: false

Related

• Webhook Processing
• Configuration & Deployment