Choose a version:

Checkout Settings API

The Checkout Settings API provides read-only access to the merchant's checkout configuration that was active when the buyer placed the order on the Order status page. Use this API to detect the order submission type, display B2B payment terms, and check shipping address editability.

Checkout settings reflect the merchant's configuration at the time of checkout. If the merchant updates their settings after an order is placed, the values returned by this API don't change.

Anchor to Use casesUse cases

Detect order type: Determine whether the order is a standard order or a draft order, and adjust your extension's behavior accordingly.
Display payment terms: If B2B payment terms are configured, display the due date and terms name to the buyer.
Check shipping address editability: Determine whether the buyer was able to modify their shipping address during checkout.

Support

Targets (10)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides the checkout settings. Access the following property on shopify to read the checkout configuration for the order.

Anchor to checkoutSettings checkoutSettings <> required: The checkout settings that were active when the buyer placed the order, such as whether order notes and login are enabled.

Returns the merchant's checkout configuration at the time of checkout. Doesn't reflect updates made after the order was placed.

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

CheckoutSettings

Settings describing the behavior of the buyer's checkout.

orderSubmission
The type of order created when the buyer completes checkout. - `'DRAFT_ORDER'`: The checkout creates a draft order that the merchant must manually confirm before fulfillment. Common for B2B checkouts with deferred payment terms. - `'ORDER'`: The checkout creates a confirmed order immediately upon completion.
```
'DRAFT_ORDER' | 'ORDER'
```
paymentTermsTemplate
The payment terms configured by the merchant for B2B orders, such as net-30 or net-60. The value is `undefined` if no payment terms are configured.
```
PaymentTermsTemplate
```
shippingAddress
Settings that control how the shipping address behaves during checkout, such as whether the buyer can edit the address.
```
ShippingAddressSettings
```

PaymentTermsTemplate

A payment terms template configured by the merchant, defining when payment is due for B2B orders. Common examples include "Net 30" (due in 30 days) or "Due on receipt".

dueDate
The due date for payment in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ss.sssZ`). The value is `undefined` if the payment terms don't have a fixed due date.
```
string
```
dueInDays
The number of days the buyer has to pay after the order is placed, such as `30` for "Net 30" terms. The value is `undefined` if the payment terms aren't net-based.
```
number
```
id
A globally-unique identifier for the payment terms template in the format `gid://shopify/PaymentTermsTemplate/<id>`.
```
string
```
name
The name of the payment terms translated to the buyer's current language, such as "Net 30" or "Due on receipt".
```
string
```

ShippingAddressSettings

Settings describing the behavior of the shipping address.

isEditable
Whether the buyer is allowed to edit the shipping address during checkout. When `false`, the shipping address is locked and can't be changed, which is common for B2B orders with a predefined ship-to address.
```
boolean
```

Examples

jsx

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

import {render} from 'preact';

export default async () => {

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

};

function Extension() {

const {orderSubmission} =

shopify.checkoutSettings.value;

const isDraftOrder =

orderSubmission === 'DRAFT_ORDER';

return (

<s-box padding="base">

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

<s-text type="strong">Order Type</s-text>

{isDraftOrder ? (

<s-banner tone="info">

This is a draft order. It will be

finalized once payment is confirmed.

</s-banner>

) : (

<s-text color="subdued">

Standard order — payment has been

processed.

</s-text>

)}

</s-stack>

</s-box>

);

}

Examples

Description

Determine whether the order is a standard order or a draft order. This example reads `shopify.checkoutSettings.orderSubmission` and displays a different label depending on the value.

jsx

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

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

function Extension() {
  const {orderSubmission} =
    shopify.checkoutSettings.value;

  const isDraftOrder =
    orderSubmission === 'DRAFT_ORDER';

  return (
    <s-box padding="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">Order Type</s-text>
        {isDraftOrder ? (
          <s-banner tone="info">
            This is a draft order. It will be
            finalized once payment is confirmed.
          </s-banner>
        ) : (
          <s-text color="subdued">
            Standard order — payment has been
            processed.
          </s-text>
        )}
      </s-stack>
    </s-box>
  );
}

Description

Show B2B payment terms including the terms name and due date. This example reads `shopify.checkoutSettings.paymentTermsTemplate` and renders the payment details when configured.

jsx

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

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

function Extension() {
  const {paymentTermsTemplate} =
    shopify.checkoutSettings.value;

  if (!paymentTermsTemplate) {
    return null;
  }

  const {dueDate, name} = paymentTermsTemplate;

  return (
    <s-box padding="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">
          Payment Terms
        </s-text>
        <s-text>Terms: {name}</s-text>
        {dueDate && (
          <s-text>
            Due date:{' '}
            {new Date(
              dueDate,
            ).toLocaleDateString()}
          </s-text>
        )}
        <s-text color="subdued">
          Payment is expected according to the
          agreed B2B terms.
        </s-text>
      </s-stack>
    </s-box>
  );
}

Description

Determine whether the buyer was able to modify their shipping address during checkout. This example reads `shopify.checkoutSettings.shippingAddress.isEditable` and conditionally shows an edit button.

jsx

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

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

function Extension() {
  const {shippingAddress} =
    shopify.checkoutSettings.value;

  const isEditable = shippingAddress?.isEditable;

  return (
    <s-box padding="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">
          Shipping Address
        </s-text>
        {isEditable ? (
          <s-stack direction="block" gap="small-200">
            <s-text>
              You can update your shipping address
              before the order ships.
            </s-text>
            <s-button>Edit address</s-button>
          </s-stack>
        ) : (
          <s-text color="subdued">
            The shipping address for this order
            cannot be changed.
          </s-text>
        )}
      </s-stack>
    </s-box>
  );
}

Anchor to Best practicesBest practices

Adapt messaging for draft orders: When orderSubmission is DRAFT_ORDER, the order hasn't been finalized by the merchant yet. Consider adjusting your extension's messaging to indicate that the order is pending review.

Was this page helpful?