Skip to main content
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 upgrade guide to upgrade your extension.

Functions settings

Function settings targets provide configuration interfaces for Shopify Functions within the Shopify admin. These extensions allow merchants to configure function behavior through forms and input fields, storing configuration data as metafields that your function can read at runtime.

Functions settings extensions use the FunctionSettings component to handle form submission and error handling. Configuration values are stored as metafields on the function's parent resource (discount, order routing rule, or validation).

Anchor to Use casesUse cases

  • Discount configuration: Create custom interfaces for merchants to configure discount functions, such as setting percentage thresholds, quantity requirements, or product selection rules for complex discount logic.
  • Order routing rules: Build configuration forms for order routing functions that help merchants define location priority, capacity constraints, fulfillment preferences, or custom routing criteria.
  • Checkout validation: Design validation rule configuration interfaces for checkout validation functions that let merchants set validation thresholds, define blocking versus warning rules, customize error messages, or configure validation logic for cart and checkout operations.
  • Dynamic function behavior: Store configuration values as metafields that your function reads at runtime, enabling merchants to adjust function behavior without code changes or redeployment.
  • Multi-field configuration: Build forms with multiple input types (text, numbers, toggles, selections) to capture complex configuration requirements for sophisticated function logic.
Shopify admin function settings pages showing all available extension target locations.

Anchor to Discount details function settings ,[object Object]Discount details function settings target

admin.discount-details.function-settings.render

Renders a function settings extension for discount functions within the discount details page. Use this target to create configuration interfaces that let merchants customize discount behavior, such as setting percentage limits, quantity requirements, customer eligibility rules, or product selection criteria.

Extensions at this target can access the discount ID and existing metafields through the Discount Function Settings API. The extension must use the FunctionSettings component as its root element. Configuration values are saved as metafields on the discount, which your function can read when processing discount calculations.

Support
Components (35)
APIs (1)

Supported components

Available APIs

Examples
import React from 'react';
import {useState} from 'react';
import {
reactExtension,
useApi,
FunctionSettings,
BlockStack,
Banner,
NumberField,
Text,
} from '@shopify/ui-extensions-react/admin';

const TARGET = 'admin.discount-details.function-settings.render';

export default reactExtension(TARGET, () => <App />);

function App() {
const {data, applyMetafieldChange} = useApi(TARGET);
const [percentage, setPercentage] = useState(
data.metafields[0]?.value || '10'
);
const [maxAmount, setMaxAmount] = useState(
data.metafields[1]?.value || '100'
);
const [error, setError] = useState();

const handlePercentageChange = async (value) => {
setPercentage(value);
setError(undefined);
await applyMetafieldChange({
type: 'updateMetafield',
namespace: '$app:discount-config',
key: 'percentage',
value,
valueType: 'number_decimal',
});
};

const handleMaxAmountChange = async (value) => {
setMaxAmount(value);
setError(undefined);
await applyMetafieldChange({
type: 'updateMetafield',
namespace: '$app:discount-config',
key: 'max-amount',
value,
valueType: 'money',
});
};

return (
<FunctionSettings
onError={(errors) => setError(errors[0]?.message)}
>
<BlockStack>
<Banner tone="info">
Configure the discount percentage and maximum discount amount. These
settings will be applied when your function runs.
</Banner>

<NumberField
step={1}
min={1}
max={100}
suffix="%"
label="Discount percentage"
value={percentage}
onChange={handlePercentageChange}
error={error}
/>

<NumberField
step={0.01}
min={0}
prefix="$"
label="Maximum discount amount"
value={maxAmount}
onChange={handleMaxAmountChange}
error={error}
/>

<Text>
Your function will read these configuration values when calculating
discounts.
</Text>
</BlockStack>
</FunctionSettings>
);
}

Anchor to Order routing rule function settings ,[object Object]Order routing rule function settings target

admin.settings.order-routing-rule.render

Renders a function settings extension for order routing functions within the order routing settings page. Use this target to create configuration interfaces that let merchants customize order routing behavior, such as setting location priorities, capacity constraints, distance thresholds, or custom routing criteria.

Extensions at this target can access the routing rule details through the Order Routing Rule API. The extension must use the FunctionSettings component as its root element. Configuration values are saved as metafields on the order routing rule, which your function can read when determining order routing.

Support
Components (35)
APIs (1)

Supported components

Available APIs

Examples
import React from 'react';
import {useState} from 'react';
import {
reactExtension,
useApi,
FunctionSettings,
BlockStack,
Banner,
Section,
NumberField,
Checkbox,
Text,
} from '@shopify/ui-extensions-react/admin';

const TARGET = 'admin.settings.order-routing-rule.render';

export default reactExtension(TARGET, () => <App />);

function App() {
const {data, applyMetafieldsChange} = useApi(TARGET);
const existingConfig = data.rule.metafields[0]?.value
? JSON.parse(data.rule.metafields[0].value)
: {prioritizeNearestLocation: true, maxDistanceKm: 50, considerInventory: true};

const [prioritizeNearest, setPrioritizeNearest] = useState(
existingConfig.prioritizeNearestLocation
);
const [maxDistance, setMaxDistance] = useState(
existingConfig.maxDistanceKm
);
const [considerInventory, setConsiderInventory] = useState(
existingConfig.considerInventory
);
const [error, setError] = useState();

const saveConfiguration = async (updates) => {
const configuration = {
prioritizeNearestLocation: prioritizeNearest,
maxDistanceKm: parseFloat(maxDistance),
considerInventory,
...updates,
};

setError(undefined);

await applyMetafieldsChange([{
type: 'updateMetafield',
namespace: '$app:routing-config',
key: 'location-priority',
value: JSON.stringify(configuration),
valueType: 'json',
}]);
};

return (
<FunctionSettings
onError={(errors) => setError(errors[0]?.message)}
>
<BlockStack>
<Banner tone="info">
Configure how orders are routed to fulfillment locations based on
distance and inventory.
</Banner>

<Section heading="Routing rules">
<Text>Rule: {data.rule.label}</Text>
<Text>{data.rule.description}</Text>
</Section>

<Section heading="Location selection">
<BlockStack>
<Checkbox
checked={prioritizeNearest}
onChange={(value) => {
setPrioritizeNearest(value);
saveConfiguration({prioritizeNearestLocation: value});
}}
>
Prioritize nearest fulfillment location
</Checkbox>

<NumberField
label="Maximum distance (km)"
value={maxDistance}
onChange={(value) => {
setMaxDistance(value);
saveConfiguration({maxDistanceKm: parseFloat(value)});
}}
min={1}
step={1}
suffix="km"
error={error}
/>

<Checkbox
checked={considerInventory}
onChange={(value) => {
setConsiderInventory(value);
saveConfiguration({considerInventory: value});
}}
>
Only route to locations with available inventory
</Checkbox>
</BlockStack>
</Section>

<Text>
Your routing function will use these rules to determine the optimal
fulfillment location for each order.
</Text>
</BlockStack>
</FunctionSettings>
);
}

Anchor to Validation function settings ,[object Object]Validation function settings target

admin.settings.validation.render

Renders a function settings extension for checkout validation functions within the checkout rules settings page. Use this target to create configuration interfaces that let merchants customize checkout validation rules, such as setting minimum order values, quantity limits, product restrictions, or custom validation criteria.

Extensions at this target can access the validation details through the Validation Settings API. The extension must use the FunctionSettings component as its root element. Configuration values are saved as metafields on the validation, which your function can read when validating cart and checkout operations.

Support
Components (35)
APIs (1)

Supported components

Available APIs

Examples
import React from 'react';
import {useState} from 'react';
import {
reactExtension,
useApi,
FunctionSettings,
BlockStack,
Banner,
Section,
NumberField,
TextField,
Checkbox,
Text,
} from '@shopify/ui-extensions-react/admin';

const TARGET = 'admin.settings.validation.render';

export default reactExtension(TARGET, () => <App />);

function App() {
const {data, applyMetafieldChange} = useApi(TARGET);
const existingConfig = data.validation?.metafields[0]?.value
? JSON.parse(data.validation.metafields[0].value)
: {minOrderValue: 50, errorMessage: 'Minimum order value not met', blockCheckout: true};

const [minOrderValue, setMinOrderValue] = useState(existingConfig.minOrderValue);
const [errorMessage, setErrorMessage] = useState(existingConfig.errorMessage);
const [blockCheckout, setBlockCheckout] = useState(existingConfig.blockCheckout);
const [error, setError] = useState();

const saveConfiguration = async (updates) => {
const configuration = {
minOrderValue: parseFloat(minOrderValue),
errorMessage,
blockCheckout,
...updates,
};

setError(undefined);

await applyMetafieldChange({
type: 'updateMetafield',
namespace: '$app:validation-config',
key: 'min-order-value',
value: JSON.stringify(configuration),
valueType: 'json',
});
};

return (
<FunctionSettings
onError={(errors) => setError(errors[0]?.message)}
>
<BlockStack>
<Banner tone="info">
Configure minimum order value requirements for checkout. Customers
must meet this threshold to complete their purchase.
</Banner>

<Section heading="Validation rules">
<BlockStack>
<NumberField
label="Minimum order value"
value={minOrderValue}
onChange={(value) => {
setMinOrderValue(value);
saveConfiguration({minOrderValue: parseFloat(value)});
}}
min={0}
step={0.01}
prefix="$"
error={error}
/>

<TextField
label="Error message"
value={errorMessage}
onChange={(value) => {
setErrorMessage(value);
saveConfiguration({errorMessage: value});
}}
placeholder="Your order must be at least $50"
/>

<Checkbox
checked={blockCheckout}
onChange={(value) => {
setBlockCheckout(value);
saveConfiguration({blockCheckout: value});
}}
>
Block checkout when validation fails
</Checkbox>

{!blockCheckout && (
<Banner tone="warning">
When unchecked, customers will see a warning but can still
proceed to checkout.
</Banner>
)}
</BlockStack>
</Section>

<Text>
Your validation function will use these settings to validate orders
during checkout.
</Text>
</BlockStack>
</FunctionSettings>
);
}

Anchor to Best practicesBest practices

  • Use consistent metafield namespaces: Prefix your app's metafield namespaces with $app: to ensure they're owned by your app. Use descriptive namespace and key names that clearly indicate their purpose.
  • Handle errors appropriately: The FunctionSettings component provides an onError callback. Use it to display validation errors and help merchants correct their configuration.
  • Set sensible default values: Initialize form fields with reasonable defaults from existing metafields or fallback values. This prevents errors when merchants haven't configured the function yet.

Anchor to LimitationsLimitations

  • Single target per module: Each [[extensions.targeting]] entry in your TOML configuration maps one target to one module file.
  • Root component requirement: All function settings extensions must use the FunctionSettings component as their root element. This component handles integration with the native save bar.
  • Limited component set: Function settings extensions can only use form components (for example, TextField, NumberField, Select, or Checkbox). They can't use resource pickers, modals, or action extensions available to other extension types.
  • Metafield storage only: Configuration values must be stored as metafields. You can't use other storage mechanisms. Metafields have size limits, so large configurations may need to be split across multiple metafields.
  • Configuration is separate from execution: Function settings extensions only store configuration as metafields. Your Shopify Function reads this configuration at runtime through metafields for input queries. The extension can't directly modify function code, enforce validation rules, or preview function behavior.
  • Metafield type constraints: When using applyMetafieldsChange, you must specify a valid metafield type. Complex configurations often require using json type and serializing/deserializing configuration objects.
Was this page helpful?