Orders and returns SDK reference

Order lists, shipment presentation, tracking, cancellations and returns.

Import these public values from @upstorr/theme-sdk/v1. Do not import their internal source files.

buildThemeOrdersUrl

buildThemeOrdersUrl(input?: { source?: ThemeOrdersSource | null; page?: number | string | null; orderId?: string | null; basePath?: string | null; }): string

cancelThemeOrderBooking

cancelThemeOrderBooking(input: { orderId: string; bookingId: string; }): Promise<ThemeCancelBookingResponse>

cancelThemeOrderBookingAction

cancelThemeOrderBookingAction(input: { orderId: string; bookingId: string; }): Promise<{ result: ThemeCancelBookingResponse; message: string; }>

clampThemeOrdersPageSize

clampThemeOrdersPageSize(value: unknown): number

createThemeOrderBookingView

createThemeOrderBookingView(booking: ThemeOrderBooking, options?: { cancelingBookingId?: string | null; }): ThemeOrderBookingView

createThemeOrderCardFinancialView

createThemeOrderCardFinancialView(order: ThemeOrderListItem): { label: string; value: string; }

createThemeOrderCardView

createThemeOrderCardView(order: ThemeOrderListItem): ThemeOrderCardView

createThemeOrderDetailView

createThemeOrderDetailView(order: ThemeOrderDetail, options?: { cancelingBookingId?: string | null; }): ThemeOrderDetailView

createThemeOrderDigitalDownloadView

createThemeOrderDigitalDownloadView(download: ThemeOrderDigitalDownload): ThemeOrderDigitalDownloadView

createThemeOrderFinancialSummaryView

createThemeOrderFinancialSummaryView(order: ThemeOrderDetail): ThemeOrderMetaRowView[]

createThemeOrderItemSecurityDepositView

createThemeOrderItemSecurityDepositView(item: ThemeOrderDetailItem): ThemeOrderMetaRowView[]

createThemeOrderItemView

createThemeOrderItemView(item: ThemeOrderDetailItem, currency: string | null | undefined, options?: { cancelingBookingId?: string | null; }): ThemeOrderItemView

createThemeOrderReturnRequestView

createThemeOrderReturnRequestView(order: ThemeOrderDetail, selectedQuantities: Record<string, number>, reasonInput: string): ThemeOrderReturnRequestView

createThemeOrdersEditorPreview

createThemeOrdersEditorPreview(input: { source: ThemeOrdersSource; mode: ThemeOrdersEditorPreviewMode; currency: string; pageSize: number; selectedOrderId?: string | null; }): { orders: ThemeOrderDetail[]; pagination: { page: number; limit: number; total: number; totalPages: number; }; selectedOrderId: string | null; selectedOrderDetail: ThemeOrderDetail | null; }

createThemeOrdersPaginationView

createThemeOrdersPaginationView(input: { page: number; totalPages: number; source?: ThemeOrdersSource; }): ThemeOrdersPaginationView

fetchThemeOrderDetail

fetchThemeOrderDetail(input: { orderId: string; source: ThemeOrdersSource; }): Promise<ThemeOrderDetail>

fetchThemeOrders

fetchThemeOrders(input: { source: ThemeOrdersSource; page: number; limit: number; }): Promise<ThemeOrdersListResponse>

formatThemeOrderBookingLabel

formatThemeOrderBookingLabel(booking: ThemeOrderBooking): string

formatThemeOrderCurrency

formatThemeOrderCurrency(value: unknown, currencyCode?: string | null): string

formatThemeOrderDateTime

formatThemeOrderDateTime(value: string | null | undefined): string

formatThemeOrderDeliveryMethodLabel

formatThemeOrderDeliveryMethodLabel(value: unknown): string

formatThemeOrderLineTotal

formatThemeOrderLineTotal(value: unknown, currencyCode?: string | null): string

formatThemeOrderNumber

formatThemeOrderNumber(value: unknown): string

formatThemeOrderPaymentMethodLabel

formatThemeOrderPaymentMethodLabel(value: unknown): string

formatThemeOrderStatusLabel

formatThemeOrderStatusLabel(status: unknown): string

getThemeOrdersEmptyMessage

getThemeOrdersEmptyMessage(source: ThemeOrdersSource): "No draft requests found for this account." | "No orders found yet."

getThemeOrderShipmentCardMeta

getThemeOrderShipmentCardMeta(order: ThemeOrderDetail, shipment: ThemeOrderShipmentSummary): string

getThemeOrderShipmentCardTitle

getThemeOrderShipmentCardTitle(index: number, total: number): string

getThemeOrderShipmentItemCountLabel

getThemeOrderShipmentItemCountLabel(items: Array<{ item: ThemeOrderDetailItem; quantity: number; }>): string | null

getThemeOrderStatusTone

getThemeOrderStatusTone(status: unknown): "success" | "danger" | "warning" | "info" | "neutral"

getThemeOrderTrackingSummary

getThemeOrderTrackingSummary(order: ThemeOrderDetail | ThemeOrderListItem, shipments: ThemeOrderShipmentSummary[]): string

normalizeThemeOrdersPagination

normalizeThemeOrdersPagination(value: ThemeOrdersPagination | null | undefined, page: number): { page: number; limit: number; total: number; totalPages: number; }

pushThemeOrdersHistoryState

pushThemeOrdersHistoryState(input: { source?: ThemeOrdersSource | null; page?: number | string | null; orderId?: string | null; basePath?: string | null; }): void

readThemeOrdersRouteData

readThemeOrdersRouteData(data: unknown): ThemeOrdersRouteData

requestThemeOrderLocalReturn

requestThemeOrderLocalReturn(input: { orderId: string; requestId: string; reason: string; lineItems: Array<{ orderItemId: string; quantity: number; }>; }): Promise<ThemeRequestLocalReturnResponse>

resolveThemeOrderItemImage

resolveThemeOrderItemImage(item: ThemeOrderDetailItem): string

resolveThemeOrderItemImageAspectRatio

resolveThemeOrderItemImageAspectRatio(value: unknown, item: ThemeOrderDetailItem): string

resolveThemeOrderPrimaryShipment

resolveThemeOrderPrimaryShipment(shipments: ThemeOrderShipmentSummary[]): ThemeOrderShipmentSummary

resolveThemeOrderShipmentItems

resolveThemeOrderShipmentItems(order: ThemeOrderDetail, shipment: ThemeOrderShipmentSummary): Array<{ item: ThemeOrderDetailItem; quantity: number; }>

ThemeOrderBookingView

type ThemeOrderBookingView = {
    id: string;
    label: string;
    statusLabel: string;
    statusTone: string;
    bookingUrl: string;
    cancellationMessage: string | null;
    cancellationReason: string | null;
    cancellationAction: {
        visible: boolean;
        disabled: boolean;
        label: string;
    };
};

ThemeOrderCardView

type ThemeOrderCardView = {
    id: string;
    key: string;
    numberLabel: string;
    dateLabel: string;
    ariaLabel: string;
    metaRows: ThemeOrderMetaRowView[];
};

ThemeOrderDetailView

type ThemeOrderDetailView = {
    numberLabel: string;
    dateLabel: string;
    summaryRows: ThemeOrderMetaRowView[];
    deliveryAddress: {
        visible: boolean;
        title: string;
        lines: string[];
    };
    delivery: {
        timelineVisible: boolean;
        timelineTitle: string;
        emptyMessage: string;
    };
    items: ThemeOrderItemView[];
    shipments: ThemeOrderShipmentView[];
    localDeliveryJourneys: Array<{
        id: string;
        title: string;
        statusLabel: string;
        statusTone: string;
        scheduledLabel: string | null;
        riderLabel: string | null;
        trackingUrl: string | null;
        events: Array<{ id: string; label: string; meta: string }>;
    }>;
};

ThemeOrderDigitalDownloadView

type ThemeOrderDigitalDownloadView = {
    id: string;
    filename: string;
    action: {
        available: boolean;
        href: string | null;
        label: string;
    };
    metaLabel: string;
};

ThemeOrderItemView

type ThemeOrderItemView = {
    id: string;
    name: string;
    quantityLabel: string;
    metaRows: ThemeOrderMetaRowView[];
    imageUrl: string;
    lineTotalLabel: string;
    raw: ThemeOrderDetailItem;
    securityDepositRows: ThemeOrderMetaRowView[];
    bookings: ThemeOrderBookingView[];
    digitalDownloads: ThemeOrderDigitalDownloadView[];
};

ThemeOrderMetaRowView

type ThemeOrderMetaRowView = {
    id: string;
    label: string;
    value: string;
};

ThemeOrderReturnRequestView

type ThemeOrderReturnRequestView = {
    visible: boolean;
    reason: string;
    canSubmit: boolean;
    lineItems: Array<{ orderItemId: string; quantity: number }>;
    items: Array<{
        id: string;
        name: string;
        selectedQuantity: number;
        quantityOptions: number[];
    }>;
};

ThemeOrdersEditorPreviewMode

type ThemeOrdersEditorPreviewMode =
    | 'runtime'
    | 'auth'
    | 'overview'
    | 'loading'
    | 'empty-orders'
    | 'detail-empty'
    | 'detail'
    | 'pagination'
    | 'error';

themeOrdersErrorMessage

themeOrdersErrorMessage(caught: unknown, fallback: string): string

ThemeOrderShipmentView

type ThemeOrderShipmentView = {
    id: string;
    open: boolean;
    title: string;
    description: string;
    meta: string;
    statusLabel: string;
    statusTone: string;
    items: Array<{
        id: string;
        name: string;
        quantityLabel: string;
    }>;
    events: Array<{
        id: string;
        description: string;
        meta: string;
    }>;
};

ThemeOrdersLoadInput

type ThemeOrdersLoadInput = {
    source: ThemeOrdersSource;
    page: number;
    selectedOrderId: string | null;
    mode: 'replace-list' | 'refresh';
};

ThemeOrdersMobileView

type ThemeOrdersMobileView = 'list' | 'detail';

ThemeOrdersPaginationView

type ThemeOrdersPaginationView = {
    visible: boolean;
    ariaLabel: string;
    label: string;
    previous: { disabled: boolean; page: number };
    next: { disabled: boolean; page: number };
};

ThemeOrdersRouteData

type ThemeOrdersRouteData = {
    ordersResponse: ThemeOrdersPayload | null;
    orderDetail: ThemeOrderDetail | null;
    source: ThemeOrdersSource;
    page: number;
    selectedOrderId: string | null;
    customer: unknown;
};

ThemeOrdersRuntime

type ThemeOrdersRuntime = {
    source: ThemeOrdersSource;
    orders: ThemeOrderListItem[];
    pagination: ReturnType<typeof normalizeThemeOrdersPagination>;
    selectedOrderId: string | null;
    selectedOrderSource: ThemeOrdersSource | null;
    selectedOrderDetail: ThemeOrderDetail | null;
    isAuthenticated: boolean;
    isLoading: boolean;
    isRefreshing: boolean;
    isDetailLoading: boolean;
    errorMessage: string | null;
    detailErrorMessage: string | null;
    bookingActionMessage: string | null;
    cancelingBookingId: string | null;
    isRequestingReturn: boolean;
    mobileView: ThemeOrdersMobileView;
    actions: {
        loadOrders: (params: ThemeOrdersLoadInput) => Promise<void>;
        selectOrder: (orderId: string, source: ThemeOrdersSource) => Promise<void>;
        refresh: () => Promise<void>;
        clearSelectedOrder: () => void;
        cancelBooking: (bookingId: string) => Promise<void>;
        requestLocalReturn: (input: { requestId: string; reason: string; lineItems: Array<{ orderItemId: string; quantity: number }> }) => Promise<void>;
    };
};

themeOrderViewFormatters

themeOrderViewFormatters: { statusLabel: (status: unknown) => string; statusTone: (status: unknown) => "success" | "danger" | "warning" | "info" | "neutral"; }

useThemeOrders

useThemeOrders(routeData: ThemeOrdersRouteData, options: { pageSize: number; }): ThemeOrdersRuntime