Choose a version:

Order API

The Order API provides information about the placed order, including its ID, display name, confirmation number, and timestamps. Use it to show order details or check cancellation status on the Order status page.

Anchor to Use casesUse cases

Display the order number: Show the human-readable order name (for example, #1000) to the buyer.
Show order status: Check the cancellation and processing timestamps to determine and display the current order status.
Reference the confirmation number: Display the confirmation number so the buyer can reference it when contacting support.

Support

Targets (12)

Supported targets

Anchor to PropertiesProperties

The Order API object provides information about the placed order. Access the following properties on the API object to read order data.

Anchor to order order StatefulRemoteSubscribable< | undefined> required: Information about the placed order, including its ID, display name, confirmation number, and timestamps.

Order

Details about the placed order, including its identifier, display name, and processing timestamps.

cancelledAt
The date and time when the order was cancelled, in ISO 8601 format. Returns `undefined` if the order hasn't been cancelled.
```
string
```
confirmationNumber
A randomly generated alpha-numeric confirmation code for the order. Always present for orders created in 2024 and later; may be absent for older orders.
```
string
```
id
A globally-unique identifier for the order.
```
string
```
name
The merchant-facing order number that appears in the Shopify admin and on the order confirmation page.
```
string
```
processedAt
The date and time when the order was processed, in ISO 8601 format. Processing happens after checkout completes and indicates the order is available in the Shopify admin.
```
string
```

Examples

import {

reactExtension,

useOrder,

} from '@shopify/ui-extensions-react/customer-account';

import {

BlockStack,

Text,

} from '@shopify/ui-extensions/customer-account';

export default reactExtension(

'customer-account.order-status.block.render',

() => <Extension />,

);

function Extension() {

const order = useOrder();

if (!order) {

return <Text>Loading order details...</Text>;

}

return (

<Text emphasis="bold">Order {order.name}</Text>

{order.confirmationNumber && (

<Text>

Confirmation: {order.confirmationNumber}

</Text>

)}

{order.processedAt && (

Placed on{' '}

{new Date(order.processedAt).toLocaleDateString()}

</Text>

)}

</BlockStack>

);

}

Examples

Description

Read the order details and display the order name, confirmation number, and processing date. This example uses the `useOrder` hook and formats the timestamps for display.

React

import {
  reactExtension,
  useOrder,
} from '@shopify/ui-extensions-react/customer-account';
import {
  BlockStack,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const order = useOrder();

  if (!order) {
    return <Text>Loading order details...</Text>;
  }

  return (
    <BlockStack>
      <Text emphasis="bold">Order {order.name}</Text>
      {order.confirmationNumber && (
        <Text>
          Confirmation: {order.confirmationNumber}
        </Text>
      )}
      {order.processedAt && (
        <Text appearance="subdued">
          Placed on{' '}
          {new Date(order.processedAt).toLocaleDateString()}
        </Text>
      )}
    </BlockStack>
  );
}

TS

import {
  extension,
  BlockStack,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const order = api.order.current;

    if (!order) {
      root.appendChild(
        root.createComponent(Text, {}, 'Loading order details...'),
      );
      return;
    }

    const stack = root.createComponent(BlockStack, {});
    stack.appendChild(
      root.createComponent(
        Text,
        {emphasis: 'bold'},
        `Order ${order.name}`,
      ),
    );
    if (order.confirmationNumber) {
      stack.appendChild(
        root.createComponent(
          Text,
          {},
          `Confirmation: ${order.confirmationNumber}`,
        ),
      );
    }
    if (order.processedAt) {
      stack.appendChild(
        root.createComponent(
          Text,
          {appearance: 'subdued'},
          `Placed on ${new Date(order.processedAt).toLocaleDateString()}`,
        ),
      );
    }
    root.appendChild(stack);
  },
);

Description

Check whether the order has been cancelled and display the cancellation date. This example uses `useOrder` and checks the `cancelledAt` property for a truthy value.

React

import {
  reactExtension,
  useOrder,
} from '@shopify/ui-extensions-react/customer-account';
import {
  Banner,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const order = useOrder();

  if (!order?.cancelledAt) {
    return null;
  }

  return (
    <Banner status="critical" title="Order cancelled">
      <Text>
        This order was cancelled on{' '}
        {new Date(order.cancelledAt).toLocaleDateString()}.
      </Text>
    </Banner>
  );
}

TS

import {
  extension,
  Banner,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const order = api.order.current;

    if (!order?.cancelledAt) return;

    const banner = root.createComponent(
      Banner,
      {status: 'critical', title: 'Order cancelled'},
    );
    banner.appendChild(
      root.createComponent(
        Text,
        {},
        `This order was cancelled on ${new Date(order.cancelledAt).toLocaleDateString()}.`,
      ),
    );
    root.appendChild(banner);
  },
);

Description

Read the confirmation number from the order and display it in a prominent banner. This example uses `useOrder` and gracefully handles older orders where `confirmationNumber` may be absent.

React

import {
  reactExtension,
  useOrder,
} from '@shopify/ui-extensions-react/customer-account';
import {Text} from '@shopify/ui-extensions/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const order = useOrder();

  if (!order?.confirmationNumber) {
    return null;
  }

  return (
    <Text>
      Confirmation number: {order.confirmationNumber}
    </Text>
  );
}

TS

import {
  extension,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const order = api.order.current;

    if (!order?.confirmationNumber) return;

    root.appendChild(
      root.createComponent(
        Text,
        {},
        `Confirmation number: ${order.confirmationNumber}`,
      ),
    );
  },
);

Anchor to Best practicesBest practices

Handle undefined order: The order property may be undefined before the order is fully processed. Always check for undefined before accessing order fields.
Use confirmationNumber for buyer-facing display: The confirmationNumber is a short, readable identifier. The id is a GID intended for API calls, not for display.

Anchor to LimitationsLimitations

The Order API provides summary-level information only. For detailed order data such as fulfillments or transactions, use the GraphQL Admin API through a backend service.

Was this page helpful?