Skip to main content

​
The shopping flow

Henry’s features are modular - use just the ones you need. You can call cart.checkout.purchase with a product link directly, use products.details without ever touching the cart, or run the full pipeline end-to-end:

​
Async jobs

Product search, product details, and checkout details are async operations. When you call them, Henry immediately returns a refId and a status. You can either set a webhook callback or poll the corresponding poll* method until status becomes complete (or handle failed). Statuses:
StatusMeaning
pendingQueued, not started yet
processingActively running
completeResults are ready in result
failedHit an unrecoverable error - check error
See Polling for a reusable helper and retry strategies, or Webhooks to have Henry send results to you instead.

​
Cart lifecycle

Create a cart with one or more product links. From there you can add, update, or remove items freely. When ready, send the buyer to checkout. Items are identified by their product URL - no separate product ID needed. cart.create returns a checkoutUrl immediately, so there’s no extra step to set up hosted checkout.

​
Checkout modes

Hosted Checkout

Henry collects shipping, payment, and taxes via a hosted modal.

Headless Checkout

Submit payment and shipping directly from your server. Full UI control.

​
Order states

After checkout (either mode), Henry creates an order and processes it asynchronously across one or more merchants.
StatusDescription
pendingOrder received, payment not yet confirmed
processingPayment confirmed, placing items with merchants
completeAll items successfully placed - result.costs is populated
cancelledOrder could not be completed
Use orders.list({ cartId }) to fetch orders associated with a specific cart, or omit cartId to list all orders for your app.

​
Merchants

Every product link is associated with a merchant host (e.g. nike.com). You can browse supported merchants with merchants.list - useful for building merchant-selection filters before adding them to a cart.

​
Monetization

Every completed order generates a commission for your application. Henry handles payout calculations, merchant relationships, and reporting. You configure commission amounts (fixed + percent) in the settings object when creating a cart. 
await henry.cart.create({
  items: [...],
  settings: {
    commissionFeePercent: 5,          // 5% of order total
    commissionFeeFixed: { value: 1.99, currency: 'USD' }, // + $1.99 flat
  },
});