feature-order hooks

The components already use these hooks. Reach for them when you build your own UI on the same data. Open a hook for its options and what it returns.

Reading data

useOrderRead a single order by order number for the active scope.

import { useOrder } from "@evolve-storefront/feature-order/hooks";

Gated on auth, so it reports isPending (not isLoading) until the client auth context validates. Render the skeleton while isPending; only isSuccess && !data is a real 404.

function useOrder(orderNumber: string)

Returns A React Query result: data, isPending, error and the rest.

useOrderDeliveryPlanThe slot or pickup point chosen for an order, for OrderDetail's deliveryPlan.

import { useOrderDeliveryPlan } from "@evolve-storefront/feature-order/hooks";

function useOrderDeliveryPlan(orderNumber: string, options?: { enabled?: boolean | undefined; })

Option	Type	Description
enabled?	boolean

Returns A React Query result: data, isPending, error and the rest.

useOrderLineReviewsPer line of an order, whether it may be reviewed and the buyer's own review, for OrderLineReviewAction.

import { useOrderLineReviews } from "@evolve-storefront/feature-order/hooks";

function useOrderLineReviews(orderNumber: string, options?: { enabled?: boolean | undefined; })

Option	Type	Description
enabled?	boolean

Returns A React Query result: data, isPending, error and the rest.

useOrderLookupOne order by id, order number or signed link, for a page that does not know whose it is — a guest's order, a payment return, a link from a mail.

import { useOrderLookup } from "@evolve-storefront/feature-order/hooks";

function useOrderLookup(lookup: OrderLookup)

Option	Type	Description
id?	string
orderNumber?	string
signedLink?	string

Returns A React Query result: data, isPending, error and the rest.

useOrderLookupPaymentMethodsThe payment methods for an order named by public id or signed link.

import { useOrderLookupPaymentMethods } from "@evolve-storefront/feature-order/hooks";

function useOrderLookupPaymentMethods(lookup: OrderPaymentMethodsLookup, device: OrderClientDevice)

Option	Type	Description
publicId?	string
signedLink?	string

Returns A React Query result: data, isPending, error and the rest.

useOrderPaymentMethodsThe payment methods offered for an order that still owes money.

import { useOrderPaymentMethods } from "@evolve-storefront/feature-order/hooks";

Read from the order rather than from a cart: whether a method is offered depends on the amount and the buyer, and by the time an order is being paid the cart that produced it is finished with.

Gated on auth, so it reports isPending (not isLoading) until the client auth context validates. Only isSuccess && !data is a missing order — and an empty method array is a real answer, meaning nothing is offered for this amount, buyer and device, which the surface has to say out loud rather than render as an empty list.

device has no default, because the offered set genuinely differs by client and guessing would offer a method the buyer cannot complete.

function useOrderPaymentMethods(orderNumber: string, device: OrderClientDevice)

Returns A React Query result: data, isPending, error and the rest.

useOrdersRead the order history for the active scope (consumer or business).

import { useOrders } from "@evolve-storefront/feature-order/hooks";

Cancelled orders are left out unless status names them, and nothing in this package filters — the gateway pages server-side, so a filter applied after would leave pagination.totalCount disagreeing with the rows. See the README.

function useOrders(args?: { page?: number | undefined; pageSize?: number | undefined; searchTerm?: string | undefined; status?: readonly OrderStatus[] | undefined; createdFrom?: string |…)

Option	Type	Description
page?	number
pageSize?	number
searchTerm?	string	Matches an order number, a purchase-order reference, or a line item's SKU.
status?	readonly OrderStatus[]	Show only these states. Omitting it is not "all" — see above.
createdFrom?	string	Inclusive lower bound as an ISO instant, resolved in the shopper's timezone.
createdUntil?	string	Inclusive upper bound as an ISO instant.

Returns A React Query result: data, isPending, error and the rest.

useOrderStatusCountsHow many orders each status holds under the history's search and date range, for OrderHistoryStatusFilter's counts.

import { useOrderStatusCounts } from "@evolve-storefront/feature-order/hooks";

function useOrderStatusCounts(args?: { searchTerm?: string | undefined; createdFrom?: string | undefined; createdUntil?: string | undefined; })

Option	Type	Description
searchTerm?	string
createdFrom?	string
createdUntil?	string

Returns A React Query result: data, isPending, error and the rest.

Changing data

useCancelOrderClose an unpaid order whose payment has finally failed.

import { useCancelOrder } from "@evolve-storefront/feature-order/hooks";

Not the opposite of useReviseOrder, and not a variant of it. Revising hands back a cart and is reached from the resume page moments after a buyer pressed back at the provider — while the payment is still open and nothing has been reported. This is reached from the order later, by a buyer who drifted away and wants the order gone, so it can afford to wait for the provider's final word and does: FAILED only. That gate is the whole reason this is not a general cancel.

Nothing comes back but the order, now cancelled — which is also why cancelled orders drop out of history by default: an order the buyer closed themselves is not part of their purchase history.

Optional in the contract, like orderRevise: an engine that composes the revision module out answers neither, so a surface offering this must tolerate its absence.

function useCancelOrder()

Returns A React Query mutation: mutate, mutateAsync, isPending and the rest.

useCreateProductReviewReview a delivered line of an order.

import { useCreateProductReview } from "@evolve-storefront/feature-order/hooks";

function useCreateProductReview()

Returns A React Query mutation: mutate, mutateAsync, isPending and the rest.

usePayOrderPay an order that already exists.

import { usePayOrder } from "@evolve-storefront/feature-order/hooks";

The one place this call lives, so everything above it sees payOrder(variables) -> PayOrderResult and no page hand-rolls the mutation. All three routes that reach an unpaid order — a failed cart checkout, a failed quote payment, and an unpaid order found in history — are the same job with different referrers, so they share this rather than each wiring their own.

Paying an order is not a checkout. A checkout turns a subject into an order; this pays one that is already there, which is the normal state under order-first. The target is what distinguishes the two calls — type: ORDER here, type: CART for feature-cart's payment-first hook — and it is required, so neither can be mistaken for the other by omission the way an optional orderId allowed.

The return URLs are provider config rather than call-site arguments, and they go to the gateway plain — it appends the order's identifiers, which is how the page the buyer returns to knows what was paid.

Invalidates the order and its lists on success, because an order with a payment against it stops offering to be paid.

function usePayOrder(options?: PayOrderOptions)

Option	Type	Description
onRedirect?	((redirectUrl: string) => void)	Defaults to a document navigation, as the provider's page is no route of the app.
onComplete?	((result: { kind: "complete"; order: { id: string; orderNumber: string; } | null; }, variables: PayOrderVariables) => void)	The payment settled in the same call, as buying on account does.

Returns A React Query mutation: mutate, mutateAsync, isPending and the rest.

useReviseOrderReopen an unpaid order for editing: a fresh cart with the same contents, and the order cancelled.

import { useReviseOrder } from "@evolve-storefront/feature-order/hooks";

One mutation, and that is the point. A replicate + cancel pair would let a caller do half of it — replicate without cancelling leaves a duplicate order, cancel without replicating strands the buyer — and neither is something they can recover from. The backend does both or neither.

Optional by design. An engine that cannot build a cart from an order does not compose the mutation, so a surface offering this must tolerate its absence: render the pay action alone rather than a control that 400s. OrderResume takes onRevise for exactly that reason — omit it and the action is not there.

Unpaid orders only. Revising a paid one is a refund conversation, and keeping the promise this small is what makes it portable across engines.

function useReviseOrder()

Returns A React Query mutation: mutate, mutateAsync, isPending and the rest.

Other hooks

useOrderReturnUrlsOrderProvider's returnUrls, all pointing at path on this origin, where a route reads them with resolvePaymentReturn.

import { useOrderReturnUrls } from "@evolve-storefront/feature-order/hooks";

function useOrderReturnUrls(path: string): OrderReturnUrls | undefined

Returns OrderReturnUrls | undefined

useReviseErrorMessageThe localized reason a revise failed, for OrderResume's reviseError; null without one.

import { useReviseErrorMessage } from "@evolve-storefront/feature-order/hooks";

function useReviseErrorMessage(error: unknown): string | null

Returns string | null