---
title: Checkout Settings API
description: >-
  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.
api_version: 2026-04
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/account-apis/checkout-settings-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/account-apis/checkout-settings-api.md
---

# 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](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status). 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.

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

* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-)

### Properties

The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#target-apis-define-what-your-extension-does) provides the checkout settings. Access the following property on `shopify` to read the checkout configuration for the order.

* **checkoutSettings**

  **SubscribableSignalLike\<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.

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

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

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

  ```ts
  PaymentTermsTemplate
  ```

* shippingAddress

  Settings that control how the shipping address behaves during checkout, such as whether the buyer can edit the address.

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

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

  ```ts
  number
  ```

* id

  A globally-unique identifier for the payment terms template in the format \`gid://shopify/PaymentTermsTemplate/\<id>\`.

  ```ts
  string
  ```

* name

  The name of the payment terms translated to the buyer's current language, such as "Net 30" or "Due on receipt".

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

  ```ts
  boolean
  ```

Examples

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

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

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

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

***

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

***