---
title: Checkout Settings API
description: >-
  The Checkout Settings API provides the merchant's checkout configuration that
  was active when the buyer placed the order. Use it to check the order type,
  payment terms, or shipping address settings on the Order status page.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/account-apis/checkout-settings-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/account-apis/checkout-settings-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# Checkout Settings API

The Checkout Settings API provides the merchant's checkout configuration that was active when the buyer placed the order. Use it to check the order type, payment terms, or shipping address settings on the Order status page.

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

### Properties

The Checkout Settings API object provides the merchant's checkout settings. Access the following properties on the API object to read checkout configuration.

* **checkoutSettings**

  **StatefulRemoteSubscribable\<CheckoutSettings>**

  **required**

  The merchant's checkout configuration that was active when the buyer placed the order, including the order type, payment terms, and shipping address settings.

### CheckoutSettings

The merchant's checkout configuration that was active when the buyer placed the order.

* orderSubmission

  The type of order created when the buyer completes checkout: - \`'DRAFT\_ORDER'\`: A draft order that requires merchant approval before processing. - \`'ORDER'\`: A standard order that’s processed immediately.

  ```ts
  'DRAFT_ORDER' | 'ORDER'
  ```

* paymentTermsTemplate

  The merchant-configured payment terms for the order, such as net 30 or net 60 terms. Only present for B2B orders with deferred payment.

  ```ts
  PaymentTermsTemplate
  ```

* shippingAddress

  Configuration for the shipping address behavior, including whether the buyer can edit it.

  ```ts
  ShippingAddressSettings
  ```

### PaymentTermsTemplate

A payment terms template that defines when payment is due for the order, commonly used in B2B transactions.

* dueDate

  The due date for net payment terms as an ISO 8601 formatted string (\`YYYY-MM-DDTHH:mm:ss.sssZ\`).

  ```ts
  string
  ```

* dueInDays

  The number of days between the order date and the payment due date for net payment terms.

  ```ts
  number
  ```

* id

  A globally-unique identifier for the payment terms template.

  ```ts
  string
  ```

* name

  The name of the payment terms translated to the buyer's current language.

  ```ts
  string
  ```

### ShippingAddressSettings

Configuration for the shipping address on the checkout.

* isEditable

  Whether the buyer was allowed to edit the shipping address during checkout.

  ```ts
  boolean
  ```

Examples

### Examples

* ####

  ##### Description

  Read the checkout settings and display whether the order is a standard order or a draft order. This example uses the \`useCheckoutSettings\` hook to check the \`orderSubmission\` property.

  ##### React

  ```tsx
  import {
    reactExtension,
    useCheckoutSettings,
  } from '@shopify/ui-extensions-react/customer-account';
  import {Banner, Text} from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const settings = useCheckoutSettings();
    if (settings.orderSubmission !== 'DRAFT_ORDER') return null;
    return (
      <Banner status="warning" title="Draft order">
        <Text>This order requires merchant approval before processing.</Text>
      </Banner>
    );
  }
  ```

  ##### TS

  ```ts
  import {extension, Banner, Text} from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const settings = api.checkoutSettings.current;
      if (settings.orderSubmission !== 'DRAFT_ORDER') return;
      const banner = root.createComponent(Banner, {status: 'warning', title: 'Draft order'});
      banner.appendChild(root.createComponent(Text, {}, 'This order requires merchant approval before processing.'));
      root.appendChild(banner);
    },
  );
  ```

* ####

  ##### Description

  Read the payment terms and display the due date and terms name. This example uses \`useCheckoutSettings\` and check for the optional \`paymentTermsTemplate\` property.

  ##### React

  ```tsx
  import {
    reactExtension,
    useCheckoutSettings,
  } from '@shopify/ui-extensions-react/customer-account';
  import {BlockStack, Text} from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const settings = useCheckoutSettings();
    const terms = settings.paymentTermsTemplate;
    if (!terms) return null;
    return (
      <BlockStack>
        <Text emphasis="bold">Payment terms</Text>
        <Text>{terms.name}</Text>
        {terms.dueInDays !== undefined && (
          <Text appearance="subdued">Payment due in {terms.dueInDays} days</Text>
        )}
      </BlockStack>
    );
  }
  ```

  ##### TS

  ```ts
  import {extension, BlockStack, Text} from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const settings = api.checkoutSettings.current;
      const terms = settings.paymentTermsTemplate;
      if (!terms) return;
      const stack = root.createComponent(BlockStack, {});
      stack.appendChild(root.createComponent(Text, {emphasis: 'bold'}, 'Payment terms'));
      stack.appendChild(root.createComponent(Text, {}, terms.name));
      if (terms.dueInDays !== undefined) {
        stack.appendChild(root.createComponent(Text, {appearance: 'subdued'}, `Payment due in ${terms.dueInDays} days`));
      }
      root.appendChild(stack);
    },
  );
  ```

* ####

  ##### Description

  Check whether the shipping address was editable during checkout. This example reads the \`shippingAddress.isEditable\` property from the checkout settings.

  ##### React

  ```tsx
  import {
    reactExtension,
    useCheckoutSettings,
  } from '@shopify/ui-extensions-react/customer-account';
  import {Text} from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const settings = useCheckoutSettings();
    return (
      <Text appearance="subdued">
        {settings.shippingAddress.isEditable
          ? 'The shipping address was editable at checkout.'
          : 'The shipping address was pre-set by the merchant.'}
      </Text>
    );
  }
  ```

  ##### TS

  ```ts
  import {extension, Text} from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const settings = api.checkoutSettings.current;
      root.appendChild(
        root.createComponent(
          Text,
          {appearance: 'subdued'},
          settings.shippingAddress.isEditable
            ? 'The shipping address was editable at checkout.'
            : 'The shipping address was pre-set by the merchant.',
        ),
      );
    },
  );
  ```

***

## Best practices

* **Check `orderSubmission` for order type**: Use the `orderSubmission` property to determine if the order is a standard `'ORDER'` or a `'DRAFT_ORDER'` that requires merchant approval.
* **Handle optional payment terms**: The `paymentTermsTemplate` is only present for B2B orders with deferred payment. Always check for `undefined` before displaying payment terms.

***

## Limitations

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

***