Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

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.

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 Checkout Settings API object provides the merchant's checkout settings. Access the following properties on the API object to read checkout configuration.

Anchor to checkoutSettings checkoutSettings StatefulRemoteSubscribable<> 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.
```
'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.
```
PaymentTermsTemplate
```
shippingAddress
Configuration for the shipping address behavior, including whether the buyer can edit it.
```
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`).
```
string
```
dueInDays
The number of days between the order date and the payment due date for net payment terms.
```
number
```
id
A globally-unique identifier for the payment terms template.
```
string
```
name
The name of the payment terms translated to the buyer's current language.
```
string
```

ShippingAddressSettings

Configuration for the shipping address on the checkout.

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

Examples

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 (

<Text>This order requires merchant approval before processing.</Text>

</Banner>

);

}

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

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

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

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

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

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

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.',
      ),
    );
  },
);

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

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.

Was this page helpful?