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:

Discount Function Settings API

Requires the FunctionSettings component.

The Discount Function Settings API lets you build UI extensions that provide custom configuration interfaces for discount functions. Use this API to create settings pages for Shopify Functions that implement discount logic.

Anchor to Use casesUse cases

Discount configuration: Build settings interfaces for discount Shopify Functions.
Metafield storage: Store discount function configuration in metafields with proper validation.
Settings UI: Create custom configuration experiences for discount logic and rules.
Function integration: Configure Shopify Functions that implement custom discount behavior.

Support

Targets (1)

Supported targets

admin.discount-details.function-settings.render

Anchor to applyMetafieldChange
applyMetafieldChange(
change
)

Updates or removes metafields that store discount function configuration data. Accepts a change object with the operation type, key, namespace, value, and value type.

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 discount function settings. Provides access to the discount identifier and associated metafields that store function configuration values. Use this data to populate your settings UI and understand the current function configuration in the admin.discount-details.function-settings.render target.

Anchor to id id required: The discount being configured by the merchant. Use this ID to associate configuration changes with the correct discount.
Anchor to metafields metafields [] required: An array of metafields that store the discount function's configuration values. Use these metafields to populate your settings UI with the current discount configuration and display existing settings to merchants.

Discount

A discount that is being configured by the merchant. Use this to access the discount's unique identifier when saving configuration changes or making GraphQL queries.

id
The discount's unique global identifier (GID) in the [GraphQL Admin API](/docs/api/admin-graphql) format (for example, `gid://shopify/DiscountAutomaticApp/123`). Use this ID to associate settings with the correct discount or query discount data.
```
string
```

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

import React, {useState} from 'react';

import {

reactExtension,

useApi,

TextField,

Button,

Banner,

} from '@shopify/ui-extensions-react/admin';

const ConfigureDiscountThreshold = () => {

const {applyMetafieldChange} = useApi<'admin.discount-details.function-settings.render'>();

const [threshold, setThreshold] = useState('50.00');

const [saved, setSaved] = useState(false);

const handleSave = async () => {

const result = await applyMetafieldChange({

type: 'updateMetafield',

namespace: 'discount-config',

key: 'minimum_purchase',

value: threshold,

valueType: 'number_decimal',

});

if (result.type === 'success') {

setSaved(true);

} else {

console.error('Configuration failed:', result.message);

}

};

return (

<TextField

label="Minimum purchase amount"

value={threshold}

onChange={setThreshold}

{saved && <Banner tone="success">Threshold configured!</Banner>}

</>

);

};

export default reactExtension(

'admin.discount-details.function-settings.render',

() => <ConfigureDiscountThreshold />,

);

Examples

Configure discount threshold

Description

Save a minimum purchase threshold to a metafield with decimal number validation. This example uses a [text field](/docs/api/admin-extensions/2025-07/ui-components/forms/textfield) for input, calls `applyMetafieldChange`, and displays a success or error [banner](/docs/api/admin-extensions/2025-07/ui-components/feedback-and-status-indicators/banner).

React

import React, {useState} from 'react';
import {
  reactExtension,
  useApi,
  TextField,
  Button,
  Banner,
} from '@shopify/ui-extensions-react/admin';

const ConfigureDiscountThreshold = () => {
  const {applyMetafieldChange} = useApi<'admin.discount-details.function-settings.render'>();
  const [threshold, setThreshold] = useState('50.00');
  const [saved, setSaved] = useState(false);

  const handleSave = async () => {
    const result = await applyMetafieldChange({
      type: 'updateMetafield',
      namespace: 'discount-config',
      key: 'minimum_purchase',
      value: threshold,
      valueType: 'number_decimal',
    });

    if (result.type === 'success') {
      setSaved(true);
    } else {
      console.error('Configuration failed:', result.message);
    }
  };

  return (
    <>
      <TextField
        label="Minimum purchase amount"
        value={threshold}
        onChange={setThreshold}
      />
      <Button title="Save Threshold" onPress={handleSave} />
      {saved && <Banner tone="success">Threshold configured!</Banner>}
    </>
  );
};

export default reactExtension(
  'admin.discount-details.function-settings.render',
  () => <ConfigureDiscountThreshold />,
);

TS

import {extension, TextField, Button, Banner} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.discount-details.function-settings.render',
  (root, api) => {
    const {applyMetafieldChange} = api;

    let threshold = '50.00';
    let savedBanner;

    const textField = root.createComponent(TextField, {
      label: 'Minimum purchase amount',
      value: threshold,
      onChange: (value) => {
        threshold = value;
      },
    });

    const saveButton = root.createComponent(Button, {
      title: 'Save Threshold',
      onPress: async () => {
        const result = await applyMetafieldChange({
          type: 'updateMetafield',
          namespace: 'discount-config',
          key: 'minimum_purchase',
          value: threshold,
          valueType: 'number_decimal',
        });

        if (result.type === 'success') {
          if (savedBanner) {
            root.removeChild(savedBanner);
          }
          savedBanner = root.createComponent(
            Banner,
            {status: 'success'},
            'Threshold configured!',
          );
          root.appendChild(savedBanner);
        } else {
          console.error('Configuration failed:', result.message);
        }
      },
    });

    root.appendChild(textField);
    root.appendChild(saveButton);
  },
);

Configure eligibility rules

Description

Save multiple discount configuration settings in a single operation. This example stores customer tags as JSON and usage limits as an integer, demonstrating how to apply multiple metafield changes sequentially.

React

import React, {useState} from 'react';
import {
  reactExtension,
  useApi,
  TextField,
  NumberField,
  Button,
  BlockStack,
} from '@shopify/ui-extensions-react/admin';

const ConfigureEligibilityRules = () => {
  const {applyMetafieldChange} = useApi<'admin.discount-details.function-settings.render'>();
  const [tags, setTags] = useState('vip, wholesale, premium');
  const [maxUses, setMaxUses] = useState('5');

  const handleSave = async () => {
    await applyMetafieldChange({
      type: 'updateMetafield',
      namespace: 'discount-config',
      key: 'eligible_customer_tags',
      value: JSON.stringify(tags.split(',').map((t) => t.trim())),
      valueType: 'json',
    });

    await applyMetafieldChange({
      type: 'updateMetafield',
      namespace: 'discount-config',
      key: 'max_uses_per_customer',
      value: maxUses,
      valueType: 'number_integer',
    });
  };

  return (
    <BlockStack>
      <TextField
        label="Eligible customer tags (comma-separated)"
        value={tags}
        onChange={setTags}
      />
      <NumberField
        label="Max uses per customer"
        value={maxUses}
        onChange={setMaxUses}
      />
      <Button title="Save Eligibility Rules" onPress={handleSave} />
    </BlockStack>
  );
};

export default reactExtension(
  'admin.discount-details.function-settings.render',
  () => <ConfigureEligibilityRules />,
);

TS

import {extension, TextField, NumberField, Button, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.discount-details.function-settings.render',
  (root, api) => {
    const {applyMetafieldChange} = api;

    let tags = 'vip, wholesale, premium';
    let maxUses = '5';

    const stack = root.createComponent(BlockStack);

    const tagsField = root.createComponent(TextField, {
      label: 'Eligible customer tags (comma-separated)',
      value: tags,
      onChange: (value) => {
        tags = value;
      },
    });

    const maxUsesField = root.createComponent(NumberField, {
      label: 'Max uses per customer',
      value: maxUses,
      onChange: (value) => {
        maxUses = value;
      },
    });

    const saveButton = root.createComponent(Button, {
      title: 'Save Eligibility Rules',
      onPress: async () => {
        await applyMetafieldChange({
          type: 'updateMetafield',
          namespace: 'discount-config',
          key: 'eligible_customer_tags',
          value: JSON.stringify(tags.split(',').map((t) => t.trim())),
          valueType: 'json',
        });

        await applyMetafieldChange({
          type: 'updateMetafield',
          namespace: 'discount-config',
          key: 'max_uses_per_customer',
          value: maxUses,
          valueType: 'number_integer',
        });
      },
    });

    stack.appendChild(tagsField);
    stack.appendChild(maxUsesField);
    stack.appendChild(saveButton);

    root.appendChild(stack);
  },
);

Load existing settings

Description

Load discount metafields on mount and display current configuration. This example shows reducing metafields into a settings object, checking for missing values, and applying defaults only when needed.

React

import React, {useState, useEffect} from 'react';
import {
  reactExtension,
  useApi,
  Text,
} from '@shopify/ui-extensions-react/admin';

const LoadExistingSettings = () => {
  const {data, applyMetafieldChange} = useApi<'admin.discount-details.function-settings.render'>();
  const [settings, setSettings] = useState<Record<string, string>>({});

  useEffect(() => {
    const initializeSettings = async () => {
      const existingSettings = data.metafields.reduce((acc, field) => {
        acc[field.key] = field.value;
        return acc;
      }, {});

      setSettings(existingSettings);

      if (!existingSettings.eligible_tags) {
        await applyMetafieldChange({
          type: 'updateMetafield',
          namespace: 'discount-config',
          key: 'eligible_tags',
          value: JSON.stringify(['vip', 'wholesale']),
          valueType: 'json',
        });
      }
    };

    initializeSettings();
  }, [data, applyMetafieldChange]);

  return (
    <>
      <Text>Current settings:</Text>
      {Object.entries(settings).map(([key, value]) => (
        <Text key={key}>
          {key}: {String(value)}
        </Text>
      ))}
    </>
  );
};

export default reactExtension(
  'admin.discount-details.function-settings.render',
  () => <LoadExistingSettings />,
);

TS

import {extension, Text} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.discount-details.function-settings.render',
  (root, api) => {
    const {data, applyMetafieldChange} = api;

    const initializeSettings = async () => {
      const existingSettings = data.metafields.reduce((acc, field) => {
        acc[field.key] = field.value;
        return acc;
      }, {});

      const headerText = root.createComponent(Text, {}, 'Current settings:');
      root.appendChild(headerText);

      Object.entries(existingSettings).forEach(([key, value]) => {
        const settingText = root.createComponent(Text, {}, `${key}: ${String(value)}`);
        root.appendChild(settingText);
      });

      if (!existingSettings.eligible_tags) {
        await applyMetafieldChange({
          type: 'updateMetafield',
          namespace: 'discount-config',
          key: 'eligible_tags',
          value: JSON.stringify(['vip', 'wholesale']),
          valueType: 'json',
        });
      }
    };

    initializeSettings();
  },
);

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 are subject to size limits. Individual metafield values can't exceed 256KB, and total metafields per resource have storage limits.
The applyMetafieldChange method is sequential. Operations are processed one at a time. Rapid successive calls might lead to race conditions where new updates overwrite earlier ones.
Metafield changes are applied immediately. Unlike some admin forms, metafield changes persist right away without waiting for the merchant to save the discount.

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

Discount

Metafield

Anchor to Best practicesBest practices

Anchor to LimitationsLimitations

Anchor to applyMetafieldChange
applyMetafieldChange(
change
)