---
title: Order API
description: >-
  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.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/order-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/order-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# 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.

### Use 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

* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)

### Properties

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

* **order**

  **StatefulRemoteSubscribable\<Order | 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.

  ```ts
  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.

  ```ts
  string
  ```

* id

  A globally-unique identifier for the order.

  ```ts
  string
  ```

* name

  The merchant-facing order number that appears in the Shopify admin and on the order confirmation page.

  ```ts
  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.

  ```ts
  string
  ```

Examples

### 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

  ```tsx
  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

  ```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

  ```tsx
  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

  ```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

  ```tsx
  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

  ```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}`,
        ),
      );
    },
  );
  ```

***

## Best 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.

***

## Limitations

* The Order API provides summary-level information only. For detailed order data such as fulfillments or transactions, use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql) through a backend service.

***