Skip to main content

Overview

Several Henry operations are async - they return immediately with a refId 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 support mode: "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 details

Headless checkout

Purchase is async too - Henry places the order with the merchant(s) in the background. An order can stay processing for up to an hour after an item fails, so poll with a long limit - or use webhooks instead.

Tips

The pollJob 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