---
title: Order API
description: >-
  Surface order confirmation data on the Thank you page to display order
  details, send confirmations, or trigger post-purchase flows.
api_version: 2026-07-rc
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/target-apis/checkout-apis/order-api
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/target-apis/checkout-apis/order-api.md
api_name: checkout-ui-extensions
---

# Order API

The Order API provides access to order confirmation data on the **Thank You** page. Use this API to display post-purchase information, detect first-time buyers, and present personalized offers.

Order data is read-only. There are no methods to modify order details from a checkout extension.

`OrderConfirmationApi` is available only on `purchase.thank-you` extension targets. Order data isn't accessible during the checkout flow.

If you're building an order status page extension, use the Order API for customer accounts. `OrderStatusApi` has moved there.

### Use cases

* **Display order confirmation details**: Show the buyer a summary of their completed order.
* **Detect first-time buyers**: Check whether this is the buyer's first order and display a welcome offer.
* **Present personalized post-purchase offers**: Tailor the Thank you page based on order context.

### Order confirmation properties

The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc#target-apis-define-what-your-extension-does) provides the following additional properties on `shopify` for extensions registered for the `purchase.thank-you` extension targets.

* **orderConfirmation**

  **SubscribableSignalLike\<OrderConfirmation>**

  **required**

  The order details available after the buyer completes checkout, including the order ID, order number, and whether it's the buyer's first purchase.

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

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

  ```ts
  () => 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.

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

  ```ts
  T
  ```

### OrderConfirmation

* isFirstOrder

  Whether this is the customer's first completed order with this shop. \`true\` means the buyer hasn't placed an order here before. Use this to show first-purchase messaging or trigger welcome offers.

  ```ts
  boolean
  ```

* number

  A randomly generated alpha-numeric identifier for the order, distinct from \`order.id\`. The value is \`undefined\` for orders that were created before this field was introduced. All recent orders have a number. Optional. Might not be present for orders created before 2024.

  ```ts
  string
  ```

* order

  ```ts
  { id: string; }
  ```

### Order status properties

**Note:**

This documentation has moved to customer accounts. Refer to [Order API](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-07-rc/target-apis/order-apis/order-api#properties)

Examples

### Examples

* ####

  ##### Description

  Show the human-readable order number on the Thank you page so buyers can reference it in support requests. This example reads \`shopify.orderConfirmation.value?.number\` and renders it in a banner, returning \`null\` when the number isn't available.

  ##### jsx

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

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

  function Extension() {
    const number =
      shopify.orderConfirmation.value?.number;

    if (!number) {
      return null;
    }

    return (
      <s-banner>
        Your order number is #{number}. Include
        this number in any support requests.
      </s-banner>
    );
  }
  ```

* ####

  ##### Description

  Welcome new customers with an exclusive discount on the Thank you page. This example reads \`shopify.orderConfirmation.value?.isFirstOrder\` to display a discount code banner for new customers, with a standard confirmation for returning buyers.

  ##### jsx

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

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

  function Extension() {
    const number = shopify.orderConfirmation.value?.number;
    const isFirstOrder =
      shopify.orderConfirmation.value?.isFirstOrder;

    if (isFirstOrder) {
      return (
        <s-banner tone="success" heading="Welcome!">
          Thanks for your first order! Use code
          WELCOME10 for 10% off your next purchase.
        </s-banner>
      );
    }

    return (
      <s-text>
        Order {number ?? 'confirmed'}. Thank you for
        shopping with us!
      </s-text>
    );
  }
  ```

***

## Best practices

* **Use `order.id` for backend operations**: The `order.id` is a globally unique GID that corresponds to the order in the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql). Use it to trigger post-purchase workflows like fulfillment, analytics, or loyalty program enrollment.

***