Choose a version:

Checkout Token API

The Checkout Token API provides access to the unique token that identifies the current checkout session. Use this API to link extension activity with server-side checkout records, or display a support reference for the buyer.

The checkout token can be undefined. Always handle this state before using the value.

Anchor to Use casesUse cases

Link extension data to orders: Send the checkout token to your backend so you can join it with the REST Admin API Order checkout_token field and WebPixel data.checkout.token for cross-system debugging.
Display a support reference: Show the buyer a reference ID they can share with customer support to speed up issue resolution.

Support

Targets (33)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides token data for the current checkout. Access the following property on shopify to retrieve the checkout session identifier. Available to purchase extension targets.

Anchor to checkoutToken checkoutToken < | undefined> required: A stable ID that represents the current checkout.

The value is undefined when the checkout hasn't been created on the server yet.

Use this to correlate checkout sessions across your extension, web pixels, and backend systems.

This matches the data.checkout.token field in a checkout-related WebPixel event and the checkout_token field in the REST Admin API Order resource.

Can be undefined. Handle the undefined state before using the value.

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

CheckoutToken

string

Examples

jsx

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

import {render} from 'preact';

import {useEffect, useState} from 'preact/hooks';

export default function extension() {

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

}

function Extension() {

const checkoutToken = shopify.checkoutToken.value;

const [synced, setSynced] = useState(false);

useEffect(() => {

if (checkoutToken && !synced) {

fetch('https://example.com/api/checkout', {

method: 'POST',

headers: {'Content-Type': 'application/json'},

body: JSON.stringify({token: checkoutToken}),

})

.then(() => setSynced(true))

.catch(console.error);

}

}, [checkoutToken, synced]);

return synced ? (

<s-text>Session synced</s-text>

) : null;

}

Examples

Description

Forward the checkout session identifier to your application server. This example reads `shopify.checkoutToken` and sends it to a backend endpoint using `fetch()` so your server can join it with the corresponding order record.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';

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

function Extension() {
  const checkoutToken = shopify.checkoutToken.value;
  const [synced, setSynced] = useState(false);

  useEffect(() => {
    if (checkoutToken && !synced) {
      fetch('https://example.com/api/checkout', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({token: checkoutToken}),
      })
        .then(() => setSynced(true))
        .catch(console.error);
    }
  }, [checkoutToken, synced]);

  return synced ? (
    <s-text>Session synced</s-text>
  ) : null;
}

Description

Present a reference ID that buyers can share with customer service. This example renders the checkout token inside a help banner so buyers can reference it when contacting support.

jsx

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

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

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

  if (!checkoutToken) {
    return null;
  }

  return (
    <s-banner heading="Need help?">
      Please include reference ID{' '}
      <s-text type="strong">{checkoutToken}</s-text>{' '}
      when contacting support.
    </s-banner>
  );
}

Anchor to Best practicesBest practices

Use the token as a correlation key: Store the checkout token alongside your backend events so you can join extension activity with WebPixel events (data.checkout.token) and the REST Admin API Order (checkout_token) for cross-system debugging and analytics.

Was this page helpful?