Choose a version:

Validation Settings API

Requires the function settings component.

The Validation Settings API lets you create complex validation rules for cart and checkout validation. Use this API to build custom settings interfaces for Shopify Functions that implement validation logic.

Anchor to Use casesUse cases

Validation configuration: Build settings interfaces for cart and checkout validation Functions.
Metafield management: Store and update validation rule configuration in metafields.
Settings UI: Create custom settings experiences for validation logic configuration.
Function integration: Configure Shopify Functions that implement validation behavior.

Support

Targets (1)

Supported targets

admin.settings.validation.render

Anchor to applyMetafieldChange
applyMetafieldChange(
change
)

Applies a metafield change to the validation settings. Use this method to update or remove metafields that store validation function configuration data. The method accepts a change object specifying the operation type, metafield key, namespace, value, and value type. Returns a promise that resolves to indicate success or provides an error message if the operation fails.

Anchor to applyMetafieldChange-parametersParameters

Anchor to change change required

Anchor to applyMetafieldChange-returnsReturns

Promise<>

MetafieldChange

A metafield change operation that can either update or remove a metafield. Pass this to `applyMetafieldChange` to modify discount settings stored in metafields.

MetafieldUpdateChange | MetafieldRemoveChange

MetafieldUpdateChange

A metafield update or creation operation. Use this to set or modify metafield values that store discount function configuration data.

key
The unique key identifying the metafield within its namespace. Use descriptive keys that indicate the setting's purpose (for example, `'min_purchase_amount'` or `'eligible_customer_tags'`).
```
string
```
namespace
The namespace that organizes related metafields. When omitted, a default namespace is assigned. Use consistent namespaces to group related settings.
```
string
```
type
Identifies this as an update operation. Always set to `'updateMetafield'` for updates.
```
'updateMetafield'
```
value
The metafield value to store. Can be a string or number depending on your configuration needs.
```
string | number
```
valueType
The [data type](/docs/apps/build/metafields/list-of-data-types) that defines how the value is formatted and validated. When omitted, preserves the existing type for updates or uses a default for new metafields. Choose a type that matches your value format.
```
SupportedDefinitionType
```

SupportedDefinitionType

The supported [metafield definition types](/docs/apps/build/metafields/list-of-data-types) for storing extension configuration data. Use these types to specify how metafield values should be formatted, validated, and displayed. Types prefixed with `list.` store arrays of values, while other types store single values. Choose a type that matches your data format (for example, use `'number_integer'` for whole numbers, `'single_line_text_field'` for short text, or `'json'` for complex structured data).

'boolean' | 'collection_reference' | 'color' | 'date' | 'date_time' | 'dimension' | 'file_reference' | 'json' | 'metaobject_reference' | 'mixed_reference' | 'money' | 'multi_line_text_field' | 'number_decimal' | 'number_integer' | 'page_reference' | 'product_reference' | 'rating' | 'rich_text_field' | 'single_line_text_field' | 'product_taxonomy_value_reference' | 'url' | 'variant_reference' | 'volume' | 'weight' | 'list.collection_reference' | 'list.color' | 'list.date' | 'list.date_time' | 'list.dimension' | 'list.file_reference' | 'list.metaobject_reference' | 'list.mixed_reference' | 'list.number_decimal' | 'list.number_integer' | 'list.page_reference' | 'list.product_reference' | 'list.rating' | 'list.single_line_text_field' | 'list.url' | 'list.variant_reference' | 'list.volume' | 'list.weight'

MetafieldRemoveChange

A metafield removal operation. Use this to delete metafields that are no longer needed for your discount configuration.

key
The unique key of the metafield to remove. Must match the key used when the metafield was created.
```
string
```
namespace
The namespace containing the metafield to remove. Required to ensure the correct metafield is targeted, as the same key can exist in different namespaces.
```
string
```
type
Identifies this as a removal operation. Always set to `'removeMetafield'` for deletions.
```
'removeMetafield'
```

MetafieldChangeResult

The result returned after attempting to change a metafield. Check the `type` property to determine if the operation succeeded (`'success'`) or failed (`'error'`), then handle the result appropriately in your extension.

MetafieldChangeSuccess | MetafieldChangeResultError

MetafieldChangeSuccess

A successful metafield change operation result. The metafield was updated or removed as requested and the changes are now saved.

type
Indicates the operation succeeded. When this value is `'success'`, the metafield change was applied successfully.
```
'success'
```

MetafieldChangeResultError

A failed metafield change operation result. Use the error message to understand what went wrong and fix the issue, such as validation errors, permission problems, or invalid metafield types.

message
A human-readable error message explaining why the operation failed. Use this to debug issues or display feedback to merchants.
```
string
```
type
Indicates the operation failed. Check this value to determine if you need to handle an error.
```
'error'
```

Anchor to datadata

The data object exposed to the extension containing the validation settings. Provides access to the validation object with its identifier and metafields, plus the Shopify Function identifier. Use this data to populate your settings UI and understand the current validation configuration in the admin.settings.validation.render target.

Anchor to shopifyFunction shopifyFunction required: The Shopify Function that implements the validation logic. Use this ID to associate configuration changes with the correct function.
Anchor to validation validation: The validation configuration containing the validation ID and metafields. Present when editing an existing validation, absent when creating a new validation. Use the presence of this value to determine if you're in create or edit mode.

ShopifyFunction

A [Shopify Function](/docs/apps/build/functions) that implements cart and checkout validation logic. This identifies which function the settings interface is configuring.

id
The [Shopify Function's](/docs/apps/build/functions) unique global identifier (GID). Use this ID to associate settings changes with the correct function.
```
string
```

Validation

A validation configuration that exists and is active in the shop. Use this object to access the validation's current settings and metafields when merchants edit an existing validation.

id
The validation's unique global identifier (GID). Use this ID to reference the validation in GraphQL operations or when saving updated settings.
```
string
```
metafields
An array of [metafields](/docs/apps/build/metafields) that store the validation's configuration values. Use these metafields to populate your settings UI with the current validation configuration.
```
Metafield[]
```

Metafield

A [metafield](/docs/apps/build/metafields) that stores discount function configuration data. Use metafields to persist settings that control how your discount function behaves, such as discount thresholds, eligibility rules, or custom discount logic parameters.

description
A human-readable description explaining the metafield's purpose and how it affects discount behavior. Use this to document your settings for other developers.
```
string
```
id
The unique global identifier (GID) for this metafield. Use this ID to reference the metafield in GraphQL queries or updates.
```
string
```
key
The unique key identifying this metafield within its namespace. This key determines how you access the metafield value (for example, `'min_purchase_amount'` or `'eligible_customer_tags'`).
```
string
```
namespace
The namespace that organizes related metafields together. All metafields for a discount should use a consistent namespace to group related settings.
```
string
```
type
The metafield [definition type](/docs/apps/build/metafields/list-of-data-types) that specifies the value format and validation rules. Use this to determine how to parse and display the value.
```
string
```
value
The metafield value stored as a string. Parse this value according to the metafield type to use it in your settings UI.
```
string
```

Examples

jsx

import {render} from 'preact';

import {useState} from 'preact/hooks';

export default async () => {

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

};

function Extension() {

const [quantity, setQuantity] = useState('3');

const [result, setResult] = useState(null);

const handleSave = async () => {

const res = await shopify.applyMetafieldChange({

type: 'updateMetafield',

namespace: 'validation',

key: 'minimum_quantity',

value: quantity,

valueType: 'number_integer',

});

setResult(res);

};

return (

<s-function-settings>

<s-number-field

label="Minimum quantity"

value={quantity}

onChange={(value) => setQuantity(value)}

<s-button onClick={handleSave}>Save Validation</s-button>

{result?.type === 'success' && (

<s-banner tone="success">Minimum quantity configured</s-banner>

)}

{result?.type === 'error' && (

<s-banner tone="critical">{result.message}</s-banner>

)}

</s-function-settings>

);

}

Examples

Description

Save a minimum quantity validation rule with a [number field](/docs/api/admin-extensions/latest/web-components/forms/number-field) input. This example calls `applyMetafieldChange`, checks the result type, and displays success or error banners based on the response.

jsx

import {render} from 'preact';
import {useState} from 'preact/hooks';

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

function Extension() {
  const [quantity, setQuantity] = useState('3');
  const [result, setResult] = useState(null);

  const handleSave = async () => {
    const res = await shopify.applyMetafieldChange({
      type: 'updateMetafield',
      namespace: 'validation',
      key: 'minimum_quantity',
      value: quantity,
      valueType: 'number_integer',
    });

    setResult(res);
  };

  return (
    <s-function-settings>
      <s-number-field
        label="Minimum quantity"
        value={quantity}
        onChange={(value) => setQuantity(value)}
      />
      <s-button onClick={handleSave}>Save Validation</s-button>
      {result?.type === 'success' && (
        <s-banner tone="success">Minimum quantity configured</s-banner>
      )}
      {result?.type === 'error' && (
        <s-banner tone="critical">{result.message}</s-banner>
      )}
    </s-function-settings>
  );
}

Description

Block shipping to specific countries with custom error messages. This example saves blocked countries as a JSON array and a custom error message, then displays the validation and function IDs.

jsx

import {render} from 'preact';
import {useState} from 'preact/hooks';

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

function Extension() {
  const {data} = shopify;
  const [countries, setCountries] = useState('US, CA, GB');
  const [errorMsg, setErrorMsg] = useState('Shipping not available to your location');

  const handleSave = async () => {
    const blockedCountries = countries.split(',').map((c) => c.trim());

    await shopify.applyMetafieldChange({
      type: 'updateMetafield',
      namespace: 'validation',
      key: 'blocked_shipping_countries',
      value: JSON.stringify(blockedCountries),
      valueType: 'json',
    });

    await shopify.applyMetafieldChange({
      type: 'updateMetafield',
      namespace: 'validation',
      key: 'error_message',
      value: errorMsg,
      valueType: 'single_line_text_field',
    });
  };

  return (
    <s-function-settings>
      <s-stack direction="block">
        <s-text-field
          label="Blocked countries (comma-separated)"
          value={countries}
          onChange={(value) => setCountries(value)}
        />
        <s-text-field
          label="Error message"
          value={errorMsg}
          onChange={(value) => setErrorMsg(value)}
        />
        <s-button onClick={handleSave}>Save Restrictions</s-button>
        <s-text>Validation ID: {data.validation?.id}</s-text>
        <s-text>Function ID: {data.shopifyFunction.id}</s-text>
      </s-stack>
    </s-function-settings>
  );
}

Description

Detect whether you're editing an existing validation or creating a new one. This example checks for `data.validation`, loads existing metafields if present, or initializes default settings for new validations.

jsx

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

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

function Extension() {
  const {data} = shopify;
  const [mode, setMode] = useState('loading');
  const [settings, setSettings] = useState({});

  useEffect(() => {
    const initializeSettings = async () => {
      if (data.validation) {
        const config = data.validation.metafields.reduce((acc, field) => {
          acc[field.key] = field.value;
          return acc;
        }, {});
        
        setSettings(config);
        setMode('edit');
      } else {
        await shopify.applyMetafieldChange({
          type: 'updateMetafield',
          namespace: 'validation',
          key: 'default_rule',
          value: 'require_minimum_cart_total',
          valueType: 'single_line_text_field',
        });
        
        setMode('created');
      }
    };

    initializeSettings();
  }, [data]);

  return (
    <s-function-settings>
      {mode === 'loading' && <s-spinner />}
      {mode === 'edit' && (
        <>
          <s-text>Editing existing validation</s-text>
          {Object.entries(settings).map(([key, value]) => (
            <s-text key={key}>
              {key}: {value}
            </s-text>
          ))}
        </>
      )}
      {mode === 'created' && <s-text>Created new validation configuration</s-text>}
    </s-function-settings>
  );
}

Anchor to Best practicesBest practices

Check operation result type: applyMetafieldChange returns { type: 'success' } or { type: 'error', message: string }. Errors don't throw exceptions, so always check the returned type property.

Anchor to LimitationsLimitations

Metafields have size limits. Individual values can't exceed 256KB, and total metafield storage per validation is limited.
The applyMetafieldChange method is sequential. Operations process one at a time. Rapid successive calls can cause race conditions where later updates overwrite earlier ones.
Metafield changes apply immediately. Unlike admin forms, metafield changes persist right away without waiting for merchants to save.
Your extension can't modify the Function ID. The shopifyFunctionId is read-only and determined when the validation rule is created.

Was this page helpful?

Anchor to Use casesUse cases

Supported targets

Supported targets

Anchor to applyMetafieldChangeapplyMetafieldChange(changechange)

Anchor to applyMetafieldChange-parametersParameters

Anchor to applyMetafieldChange-returnsReturns

MetafieldChange

MetafieldUpdateChange

SupportedDefinitionType

MetafieldRemoveChange

MetafieldChangeResult

MetafieldChangeSuccess

MetafieldChangeResultError

Anchor to datadata

ShopifyFunction

Validation

Metafield

Anchor to Best practicesBest practices

Anchor to LimitationsLimitations

Anchor to applyMetafieldChange
applyMetafieldChange(
change
)