Skip to main content

Build the UI for the delivery customization function

Merchants create and manage delivery customizations in the Shopify admin. Shopify uses URLs that you configure 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.

Anchor to What you'll learnWhat 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.
  • Configure the UI paths for your function.
Screenshot that shows the merchant UI for configuring the delivery function

Anchor to RequirementsRequirements

Anchor to Step 1: Create the frontend UI for your functionStep 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 React Router app template uses file-based routing, so the file name determines the page's URL. The $ prefix indicates functionId and id are dynamic segments. The path for this page is /app/delivery-customization/{functionId}/{id} .

  2. Add the following code in app.delivery-customization.$functionId.$id.jsx:

    • The 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 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 and React Router hooks.

    app/routes/app.delivery-customization.$functionId.$id.jsx

    import { useState, useEffect } from "react";
    import type { FormEvent } from "react";
    import {
    useActionData,
    useNavigation,
    useSubmit,
    useLoaderData,
    } from "react-router";
    import type { LoaderFunctionArgs, ActionFunctionArgs } from "react-router";
    import { authenticate } from "../shopify.server";

    interface LoaderData {
    headers: { "Content-Type": string };
    body: string;
    }

    interface ActionData {
    errors: Array<{ message: string }>;
    }

    interface DeliveryCustomizationData {
    stateProvinceCode: string;
    message: string;
    }

    export const loader = async ({ params, request }: LoaderFunctionArgs): Promise<LoaderData> => {
    const { 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) {

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

In the previous tutorial, 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 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.

run.graphql

src/run.graphql

query RunInput {
cart {
deliveryGroups {
deliveryAddress {
provinceCode
}
deliveryOptions {
handle
title
}
}
}
deliveryCustomization {
metafield(namespace: "$app:delivery-customization", key: "function-configuration") {
value
}
}
}
query Input {
cart {
deliveryGroups {
deliveryAddress {
provinceCode
}
deliveryOptions {
handle
title
}
}
}
deliveryCustomization {
metafield(namespace: "$app:delivery-customization", key: "function-configuration") {
value
}
}
}

Anchor to Step 3: Configure the create UI path for your functionStep 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 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.

extensions/delivery-customization/shopify.extension.toml

[ui.paths]
create = "/app/delivery-customization/function-handle/new"
details = "/app/delivery-customization/function-handle/:id"

Anchor to Step 4: Update your app access scopesStep 4: Update your app access scopes

You must request the write_delivery_customizations access scope 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.

    shopify.app.toml

    # This file stores configurations for your Shopify app.

    scopes = "write_products, write_delivery_customizations"

  2. Save your configuration file. If app dev is running, the scope changes will be applied automatically. If not, start the command:

    Terminal

    shopify app dev

Anchor to Step 5: Create and test your delivery customizationStep 5: Create and test your delivery customization

  1. From the Shopify admin, go to Settings > Shipping and delivery.
  2. Under the Delivery customizations section, click Manage.
  3. If you have existing customizations from previous tutorials, then click the checkbox next to each of them, and then click Deactivate.
  4. Click Add a customization and then click delivery-customization by {your app}.
  5. Fill in the delivery customization form, then click Save.
  1. Open your development store, build a cart, and proceed to checkout.
  2. Enter a delivery address that doesn't use the specified state/province code. You shouldn't see any additional messaging on the delivery options.
  3. 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, 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.

  2. In a new terminal window, use the Shopify CLI app function replay command to replay a function execution locally, and debug your function without the need to re-trigger the function execution on Shopify.

Terminal

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

Anchor to Deploy your appDeploy your app

When you're ready to release your changes to users, you can create and release an app version. An app version is a snapshot of your app configuration and all extensions.

  1. Navigate to your app directory.

  2. Run the following command.

    Optionally, you can provide a name or message for the version using the --version and --message flags.

    Terminal

    shopify app deploy

Releasing an app version replaces the current active version that's served to stores that have your app installed. It might take several minutes for app users to be upgraded to the new version.

Tip

If you want to create a version, but avoid releasing it to users, then run the deploy command with a --no-release flag. You can release the unreleased app version using Shopify CLI's release command, or through the Dev Dashboard.

Anchor to Next stepsNext steps

  • Review the UX guidelines to learn how to implement delivery customizations in user interfaces.
Was this page helpful?