Overview
Several Henry operations are async - they return immediately with arefId and a status, and results arrive once processing completes. You poll the corresponding poll* endpoint until status reaches a terminal state.
Operations that follow this pattern:
cart.checkout.details starts one job per merchant in the cart and returns them as data.jobs[], each with its own refId and status - poll each job’s refId separately.
Statuses
A purchase (
pollPurchase) settles as complete (every item bought), partially_complete (some items bought), failed (nothing bought) or cancelled, and can stay processing for up to an hour after an item fails — that item reads processing too until the order settles. For purchases, prefer webhooks over long polling.
Sync mode - skip polling entirely
All async operations supportmode: "sync", which blocks the request for up to 30 seconds until the operation completes. If the result is ready within that window, you get it in a single call with no polling needed.
If the operation doesn’t complete within 30 seconds, sync mode returns with a non-terminal status (
pending or processing) and you’ll need to fall back to polling. For operations that reliably take longer (e.g. headless checkout), prefer mode: "async" with the poll helper below.Reusable poll helper
This generic helper works for any Henry async operation. Drop it in a shared utility file and import it wherever you need it.Examples
Product search
Product details
Headless checkout
Purchase is async too - Henry places the order with the merchant(s) in the background. An order can stayprocessing for up to an hour after an item fails, so poll with a long limit - or use webhooks instead.
Tips
ThepollJob helper defaults to 1s intervals and 60 attempts, which works for most cases. Product search and details typically complete in 2–5 seconds; orders take longer since Henry places them with the merchant.
For order fulfillment, consider skipping polling entirely - Webhooks let Henry push results to you instead.
Next steps
Webhooks
Skip polling for order events - have Henry push results to your server instead
Order Management
List and filter orders after checkout