Choose a version:

Order API

The Order API provides read-only access to core order details on the Order status page. Use this API to identify the current order, display its status, or correlate it with data from other Shopify APIs.

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 shopify global object provides details about the placed order. Access the following properties on shopify to read the order ID, display name, confirmation number, processing date, and cancellation status.

Anchor to order order < | undefined> required: The order that was placed after checkout completion. Includes the order ID, display name, confirmation number, and timestamps for processing and cancellation. The value is undefined if the order hasn't been fully processed yet.

SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends `ReadonlySignalLike` with deprecated fields that are still supported for backwards compatibility.

current
The current value of the signal. Equivalent to `.value`, accessing this property subscribes to changes when used in a reactive context.
```
T
```
destroy
Cleans up the subscription and releases any resources held by this signal. After calling `destroy()`, the signal stops receiving updates from the main thread.
```
() => Promise<void>
```
subscribe
Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

Order

Information about an order that was placed.

cancelledAt
The date and time when the order was cancelled, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. The value is `undefined` if the order hasn't been cancelled. Use this to conditionally display cancellation details to the buyer.
```
string
```
confirmationNumber
A randomly generated alphanumeric identifier for the order that the buyer can use when contacting the merchant about their purchase. This is always present for orders created in 2024 and onwards. For older orders, this value may be `undefined`.
```
string
```
id
A globally-unique identifier for the order in the format `gid://shopify/Order/<id>`. Use this to reference the order in the [GraphQL Admin API](/docs/api/admin-graphql).
```
string
```
name
The merchant-facing order number prefixed with `#`, such as `#1001`. This is the human-readable identifier displayed to both the merchant in Shopify admin and the buyer on the **Order status** page and in email confirmations.
```
string
```
processedAt
The date and time when the order was processed, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. An order is processed after the buyer completes checkout and the payment is captured, at which point the order becomes visible in Shopify admin.
```
string
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

const order = shopify.order.value;

if (!order) {

return <s-text>Loading order details…</s-text>;

}

const formattedDate = new Date(order.processedAt ?? '').toLocaleDateString(

undefined,

{year: 'numeric', month: 'long', day: 'numeric'},

);

return (

<s-box padding="base">

<s-stack direction="block" gap="small-200">

<s-text type="strong">

Order {order.name}

</s-text>

<s-text color="subdued">Placed on {formattedDate}</s-text>

</s-stack>

</s-box>

);

}

Examples

Description

Show the human-readable order name and processing date to the buyer. This example reads `shopify.order` and displays the `name` field alongside a formatted `processedAt` timestamp.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const order = shopify.order.value;

  if (!order) {
    return <s-text>Loading order details…</s-text>;
  }

  const formattedDate = new Date(order.processedAt ?? '').toLocaleDateString(
    undefined,
    {year: 'numeric', month: 'long', day: 'numeric'},
  );

  return (
    <s-box padding="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">
          Order {order.name}
        </s-text>
        <s-text color="subdued">Placed on {formattedDate}</s-text>
      </s-stack>
    </s-box>
  );
}

Description

Display the confirmation number so the buyer can reference it for support. This example reads the `confirmationNumber` from `shopify.order` and renders it in a highlighted box.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const order = shopify.order.value;

  if (!order) {
    return <s-text>Loading…</s-text>;
  }

  return (
    <s-box padding="base" border="base" borderRadius="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">Support Reference</s-text>
        <s-text color="subdued">
          If you need to contact support, provide this confirmation number:
        </s-text>
        <s-box
          padding="small-200"
          background="subdued"
          borderRadius="small-100"
        >
          <s-text type="strong">
            {order.confirmationNumber}
          </s-text>
        </s-box>
      </s-stack>
    </s-box>
  );
}

Description

Detect whether the order has been cancelled and display the appropriate status. This example checks the `cancelledAt` timestamp on `shopify.order` and shows a warning banner if the order is cancelled.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const order = shopify.order.value;

  if (!order) {
    return <s-text>Loading…</s-text>;
  }

  if (order.cancelledAt) {
    const cancelledDate = new Date(order.cancelledAt).toLocaleDateString(
      undefined,
      {year: 'numeric', month: 'long', day: 'numeric'},
    );

    return (
      <s-banner tone="warning">
        This order was cancelled on {cancelledDate}. If you have questions about
        your refund, please contact support with order {order.name}.
      </s-banner>
    );
  }

  return (
    <s-banner tone="info">
      Order {order.name} is active and being processed.
    </s-banner>
  );
}

Anchor to Best practicesBest practices

Use name for display and id for lookups: The name property (for example, #1000) is the human-readable order number shown to buyers. Use the id property (a globally-unique GID) for API lookups and data storage.

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?