Skip to main content

Customize location rule user interface

Merchants add and manage location rules in the Shopify admin. Shopify uses Admin UI extensions to render the location rule editing experience for the merchant. You can customize this UI for your function's configuration needs, or to meet other requirements of your app.

Beta

Location rules is a new feature that's only available by request. Reach out to Shopify Plus Support to know more about your eligibility and the requirements for the beta program.

Screenshot that shows the merchant UI for configuring the location rule function

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

  • Generate starter code for location rule UI extensions.
  • Update the location rule user interface with Admin UI extensions.

Anchor to RequirementsRequirements

Anchor to Step 1: Create the location rule user interfaceStep 1: Create the location rule user interface

The following example builds a React-based Admin UI extensions that enables merchants to create and configure a location rule function.

  1. Navigate to your app directory:

    Terminal

    cd <directory>

  2. Run the following command to create a new location rule UI extension:

    Terminal

    shopify app generate extension --template order_routing_location_rule_ui --name location-rule-ui

  3. Choose the language that you want to use. For this tutorial, you should select either JavaScript or TypeScript.

    Terminal

    ? What would you like to work in?
    > (1) JavaScript React
    (2) JavaScript
    (3) TypeScript React
    (4) TypeScript

  4. Navigate to extensions/location-rule-ui:

    Terminal

    cd extensions/location-rule-ui

  5. Create a new preferredCountry state variable:

    src/OrderRoutingLocationRule.tsx

    import { useState } from 'react';

    const defaultValue = data.rule.metafields[0] ? JSON.parse(data.rule.metafields[0].value).countryCode : 'CA';
    const [preferredCountry, setPreferredCountry] = useState(defaultValue);

  6. Update your user interface to provide controls to configure the state variable:

    src/OrderRoutingLocationRule.tsx

    <Form onSubmit={handleSubmit} onReset={handleOnReset}>
    <Box padding="none none base none">
    <Select onChange={setPreferredCountry} value={preferredCountry} label='Select your preferred country' options={[{label:'Canada', value:'CA'}, {label:'United States', value: 'US'}]} />
    </Box>
    <Box padding="base none">
    <Text fontWeight="bold">
    Locations in your preferred county will be prioritized over locations in other countries
    </Text>
    </Box>
    </Form>

  7. Use the applyMetafieldsChange API to prepare your changes to be saved to your metafield:

    src/OrderRoutingLocationRule.tsx

    const handleSubmit = () => {
    const value = {
    countryCode: preferredCountry
    };

    const metafieldsChange = [
    {
    namespace: '$app:location-rule',
    key: 'preferred-country',
    type: 'updateMetafield',
    value: JSON.stringify(value),
    valueType: 'json',
    },
    ];

    applyMetafieldsChange(metafieldsChange);
    };

The contents of src/OrderRoutingLocationRule.tsx should look like this:

src/OrderRoutingLocationRule.tsx

import { useState } from 'react';

import {
reactExtension,
useApi,
Text,
Box,
Form,
Select,
} from '@shopify/ui-extensions-react/admin';

// The target used here must match the target used in the extension's toml file (./shopify.extension.toml)
const TARGET = 'admin.settings.order-routing-rule.render';

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

function App() {
// The useApi hook provides access to several useful APIs like i18n, data and applyMetafieldsChange.
const {data, applyMetafieldsChange, i18n} = useApi(TARGET);

const defaultValue = data.rule.metafields[0] ? JSON.parse(data.rule.metafields[0].value).countryCode : 'CA';
const [preferredCountry, setPreferredCountry] = useState(defaultValue);

// Transform your state into metafields and send them back to the admin to batch the
// changes together with the rest of merchant updates to the routing strategy
const handleSubmit = () => {
const value = {
countryCode: preferredCountry
};

const metafieldsChange = [
{
namespace: '$app:location-rule',
key: 'preferred-country',
type: 'updateMetafield',
value: JSON.stringify(value),
valueType: 'json',
},
];

applyMetafieldsChange(metafieldsChange);
};

// Reset your state to the default values
const handleOnReset = () => {
console.log('reset');
};

return (
<Form onSubmit={handleSubmit} onReset={handleOnReset}>
<Box padding="none none base none">
<Select onChange={setPreferredCountry} value={preferredCountry} label='Select your preferred country' options={[{label:'Canada', value:'CA'}, {label:'United States', value: 'US'}]} />
</Box>
<Box padding="base none">
<Text fontWeight="bold">
Locations in your preferred county will be prioritized over locations in other countries
</Text>
</Box>
</Form>
);
}

Anchor to Step 2: Associate the user interface to the location ruleStep 2: Associate the user interface to the location rule

To connect the location rule user interface to a location rule function, set the handle property of the extensions.ui setting in your extension config.

  1. Navigate to your app directory:

    Terminal

    cd <directory>

  2. Navigate to extensions/location-rule:

    Terminal

    cd extensions/location-rule

  3. Inside of shopify.extension.toml, under the [extensions.ui] heading, add a new key to associate the newly created location rule UI extension with the existing location rule function.

    shopify.extension.toml

    [extensions.ui]
    handle = "location-rule-ui"

  4. Restart your app:

    Terminal

    shopify app dev

Anchor to Step 3: Test the location rule user interfaceStep 3: Test the location rule user interface

You can test your location rule to ensure it's working as expected, and review logs for your function.

Before you test the location rule, make sure that you have the following:

  • Two locations in your store in different countries, one of them in Canada and the other one in the US.
  • One product that is stocked on both locations.

  1. On the Order routing settings page, click the Edit ✎ button next to your rule.

    A modal should open showing the custom location rule user interface.

  2. Select a different prioritized country.

  3. Click Done.

  4. In the context bar, click Save.

  5. Open your development store.

  6. Add products to your cart, including the one that's stocked in your Canada and US locations.

  7. Proceed through checkout.

  8. In the Shopify admin, and find your new order. This should be assigned to the location in the country you prioritized.

Was this page helpful?