Merchants create and manage delivery customizations in the Shopify admin. Shopify uses [URLs that you configure](/docs/apps/build/functions/input-output/metafields-for-input-queries#creating-your-merchant-interface) to render the delivery customization creation and editing experience for the merchant. You can customize this UI for your function's configuration needs, or to meet other requirements of your app.

## What you'll learn

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

- Create an App Bridge UI that enables users to create a [function owner](/docs/apps/build/functions/input-output/metafields-for-input-queries#how-it-works).
- Configure the UI paths for your function.


![Screenshot that shows the merchant UI for configuring the delivery function](/assets/apps/checkout/delivery-customization-merchant-ui.png)

## Requirements

- You've completed the [Add configuration to your delivery customization](/docs/apps/build/checkout/delivery-shipping/delivery-options/add-configuration) tutorial.
- You created your app with the [Remix app template](/docs/api#app-templates).

## Step 1: Create the frontend UI for your function

The following example builds a React-based page that enables merchants to create and configure a new delivery customization. The code renders a frontend page in your app and uses the GraphQL Admin API to create a delivery customization.

1. In `app/routes`, create a new file named `app.delivery-customization.$functionId.$id.jsx`.

    The Shopify Remix app template uses file-based routing, so the file name determines the page's URL. The `$` prefix indicates `functionId` and `id` are [dynamic segments](https://remix.run/docs/en/main/guides/routing#dynamic-segments). The path for this page is `/app/delivery-customization/{functionId}/{id}` .

1. Add the following code in `app.delivery-customization.$functionId.$id.jsx`:
    - The [`loader`](https://remix.run/docs/en/main/route/loader) function handles fetching the data to populate the form and is used when this page has an `id` value that is not `new`.
    - The [`action`](https://remix.run/docs/en/main/route/action) function handles submitting the form data to Shopify to create the delivery customization.
    - The `DeliveryCustomization` function renders the page and form components using [Polaris components](https://polaris.shopify.com/components) and [Remix hooks](https://remix.run/docs/en/main/hooks/use-navigation).

        

    ```javascript
    import { useState, useEffect } from "react";
    import {
      Banner,
      Card,
      FormLayout,
      Layout,
      Page,
      TextField,
    } from "@shopify/polaris";
    import {
      Form,
      useActionData,
      useNavigation,
      useSubmit,
      useLoaderData,
    } from "@remix-run/react";
    import { json } from "@remix-run/node";
    import { authenticate } from "../shopify.server";

    export const loader = async ({ params, request }) => {
      const { functionId, id } = params;
      const { admin } = await authenticate.admin(request);

      if (id != "new") {
        const gid = `gid://shopify/DeliveryCustomization/${id}`;

        const response = await admin.graphql(
          `#graphql
            query getDeliveryCustomization($id: ID!) {
              deliveryCustomization(id: $id) {
                id
                title
                enabled
                metafield(namespace: "$app:delivery-customization", key: "function-configuration") {
                  id
                  value
                }
              }
            }`,
          {
            variables: {
              id: gid,
            },
          }
        );

        const responseJson = await response.json();
        const deliveryCustomization = responseJson.data.deliveryCustomization;
        const metafieldValue = JSON.parse(deliveryCustomization.metafield.value);

        return {
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            stateProvinceCode: metafieldValue.stateProvinceCode,
            message: metafieldValue.message,
          }),
        };
      }

      return {
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          stateProvinceCode: "",
          message: "",
        }),
      };
    };

    export const action = async ({ params, request }) => {
      const { functionId, id } = params;
      const { admin } = await authenticate.admin(request);
      const formData = await request.formData();

      const stateProvinceCode = formData.get("stateProvinceCode");
      const message = formData.get("message");

      const deliveryCustomizationInput = {
        functionId,
        title: `Change ${stateProvinceCode} delivery message`,
        enabled: true,
        metafields: [
          {
            namespace: "$app:delivery-customization",
            key: "function-configuration",
            type: "json",
            value: JSON.stringify({
              stateProvinceCode,
              message,
            }),
          },
        ],
      };

      if (id != "new") {
        const response = await admin.graphql(
          `#graphql
            mutation updateDeliveryCustomization($id: ID!, $input: DeliveryCustomizationInput!) {
              deliveryCustomizationUpdate(id: $id, deliveryCustomization: $input) {
                deliveryCustomization {
                  id
                }
                userErrors {
                  message
                }
              }
            }`,
          {
            variables: {
              id: `gid://shopify/DeliveryCustomization/${id}`,
              input: deliveryCustomizationInput,
            },
          }
        );

        const responseJson = await response.json();
        const errors = responseJson.data.deliveryCustomizationUpdate?.userErrors;

        return json({ errors });
      } else {
        const response = await admin.graphql(
          `#graphql
            mutation createDeliveryCustomization($input: DeliveryCustomizationInput!) {
              deliveryCustomizationCreate(deliveryCustomization: $input) {
                deliveryCustomization {
                  id
                }
                userErrors {
                  message
                }
              }
            }`,
          {
            variables: {
              input: deliveryCustomizationInput,
            },
          }
        );

        const responseJson = await response.json();
        const errors = responseJson.data.deliveryCustomizationCreate?.userErrors;

        return json({ errors });
      }
    };

    export default function DeliveryCustomization() {
      const submit = useSubmit();
      const actionData = useActionData();
      const navigation = useNavigation();
      const loaderData = useLoaderData();

      const [stateProvinceCode, setStateProvinceCode] = useState(loaderData.stateProvinceCode);
      const [message, setMessage] = useState(loaderData.message);

      useEffect(() => {
        if (loaderData) {
          const parsedData = JSON.parse(loaderData.body);
          setStateProvinceCode(parsedData.stateProvinceCode);
          setMessage(parsedData.message);
        }
      }, [loaderData]);

      const isLoading = navigation.state === "submitting";

      useEffect(() => {
        if (actionData?.errors.length === 0) {
          open('shopify:admin/settings/shipping/customizations', '_top')
        }
      }, [actionData?.errors]);

      const errorBanner = actionData?.errors.length ? (
        <Layout.Section>
        <Banner
          title="There was an error creating the customization."
          status="critical"
        >
          <ul>
            {actionData?.errors.map((error, index) => {
              return <li key={`${index}`}>{error.message}</li>;
            })}
          </ul>
        </Banner>
      </Layout.Section>
    ) : null;

    const handleSubmit = () => {
      submit({ stateProvinceCode, message }, { method: "post" });
    };

    return (
      <Page
        title="Change delivery message"
        backAction={{
          content: "Delivery customizations",
          onAction: () => open('shopify:admin/settings/shipping/customizations', '_top')
        }}
        primaryAction={{
          content: "Save",
          loading: isLoading,
          onAction: handleSubmit,
        }}
      >
        <Layout>
          {errorBanner}
          <Layout.Section>
            <Card>
              <Form method="post">
                <FormLayout>
                  <FormLayout.Group>
                    <TextField
                      name="stateProvinceCode"
                      type="text"
                      label="State/Province code"
                      value={stateProvinceCode}
                      onChange={setStateProvinceCode}
                      disabled={isLoading}
                      requiredIndicator
                      autoComplete="on"
                    />
                    <TextField
                      name="message"
                      type="text"
                      label="Message"
                      value={message}
                      onChange={setMessage}
                      disabled={isLoading}
                      requiredIndicator
                      autoComplete="off"
                    />
                  </FormLayout.Group>
                </FormLayout>
              </Form>
            </Card>
          </Layout.Section>
        </Layout>
      </Page>
    );
    }
    ```
    
    

## Step 2: Update your input query to use an app-owned namespace

In the [previous tutorial](/docs/apps/selling-strategies/discounts/experience/config), you used a metafield namespace that was accessible to any app, so that the metafield namespace could be populated using GraphiQL. To make your function ready for production, you should update the metafield namespace to use a [reserved prefix](/docs/apps/build/custom-data/ownership#reserved-prefixes) so that other apps can't use your metafield.


Replace the code in the `extensions/delivery-customization/src/run.graphql` file with the following code. The query differs slightly in Rust and JavaScript due to code generation requirements.


```graphql?title: 'JavaScript input query', filename: 'src/run.graphql'
query RunInput {
  cart {
    deliveryGroups {
      deliveryAddress {
        provinceCode
      }
      deliveryOptions {
        handle
        title
      }
    }
  }
  deliveryCustomization {
    metafield(namespace: "$app:delivery-customization", key: "function-configuration") {
      value
    }
  }
}
```

```graphql?title: 'Rust input query', filename: 'src/run.graphql'
query Input {
  cart {
    deliveryGroups {
      deliveryAddress {
        provinceCode
      }
      deliveryOptions {
        handle
        title
      }
    }
  }
  deliveryCustomization {
    metafield(namespace: "$app:delivery-customization", key: "function-configuration") {
      value
    }
  }
}
```



## Step 3: Configure the create UI path for your function

In `shopify.extension.toml`, define the URLs that users will access to create and edit delivery customizations using your function. Shopify automatically fills in any [dynamic tokens](/docs/apps/build/functions/input-output/metafields-for-input-queries#dynamic-id-values) in these URLs.

In `extensions/delivery-customization/shopify.extension.toml`, populate the two settings directly under `[ui.paths]`. This change is automatically reflected as long as you're running `dev`.


```toml
[ui.paths]
create = "/app/delivery-customization/:functionId/new"
details = "/app/delivery-customization/:functionId/:id"
```



## Step 4: Update your app access scopes

You must request the `write_delivery_customizations` [access scope](/docs/api/usage/access-scopes) to invoke delivery customization mutations in the Admin API.

1. In `shopify.app.toml` in the root of your app, add the `write_delivery_customizations` scope.

    
    ```toml
    # This file stores configurations for your Shopify app.

    scopes = "write_products, write_delivery_customizations"
    ```

    

1. Deploy your updated configuration to Shopify:

        ```bash
shopify app deploy 
```

    

1. Restart your app:

        ```bash
shopify app dev 
```

    

1. Use the URL provided by the CLI to open and re-install your app. You should be prompted to accept the new access scope permissions in your store.

## Step 5: Create and test your delivery customization

1. From the Shopify admin, go to **Settings** > **Shipping and delivery**.
1. Under the **Delivery customizations** section, click **Manage**.
1. If you have existing customizations from previous tutorials, then click the checkbox next to each of them, and then click **Deactivate**.
1. Click **Add a customization** and then click **delivery-customization by {your app}**.
1. Fill in the delivery customization form, then click **Save**.

1. Open your development store, build a cart, and proceed to checkout.
1. Enter a delivery address that doesn't use the specified state/province code. You shouldn't see any additional messaging on the delivery options.
1. Change your shipping address to use your chosen state/province code. Your delivery options should now have the additional messaging.
1. Open your terminal where `shopify app dev` is running, and review your function executions.

    When [testing functions on development stores](/docs/apps/build/functions/test-debug-functions#test-your-function-on-a-development-store), the output of `dev` includes executions of your functions, any debug logging you have added to them, and a link to a local file with the full function execution details.
1. In a new terminal window, use the Shopify CLI [`app function replay`](/docs/api/shopify-cli/app/app-function-replay) command to [replay a function execution locally](/docs/apps/build/functions/test-debug-functions#execute-the-function-locally-using-shopify-cli), and debug your function without the need to re-trigger the function execution on Shopify.

    <p>
    <div class="react-code-block" data-preset="terminal">
    <div class="react-code-block-preload ThemeMode-dim">
    <div class="react-code-block-preload-bar "></div>
    <div class="react-code-block-preload-placeholder-container">
    <div class="react-code-block-preload-code-container">
    <div class="react-code-block-preload-codeline-number"></div>
    <div class="react-code-block-preload-codeline"></div>
    </div>

    </div>
    </div>


    <script type="text/plain" data-language="bash">
    RAW_MD_CONTENTshopify app function replay
    END_RAW_MD_CONTENT</script>

    </div>
    </p>


1. Select the function execution from the top of the list. Press `q` to quit when you are finished debugging.



## Next steps


- Learn more about how [Shopify Functions](/docs/apps/build/functions) work and the benefits of using Shopify Functions.
- Consult the [API references for Shopify Functions](/docs/api/functions).
- Learn how to use [variables](/docs/apps/build/functions/input-output/use-variables-input-queries) in your input query.


- Review the [UX guidelines](/docs/apps/build/checkout/delivery-shipping/delivery-options/ux-for-delivery-options) to learn how to implement delivery customizations in user interfaces.