Build a pre-purchase Shopify checkout UI extension 

1import { applyParams, save, ActionOptions } from "gadget-server";
2import { preventCrossShopDataAccess } from "gadget-server/shopify";
3
4export const run: ActionRun = async ({
5  params,
6  record,
7  logger,
8  api,
9  connections,
10}) => {
11  applyParams(params, record);
12  await preventCrossShopDataAccess(params, record);
13
14  try {
15    // get an embedding for the product title + description using the OpenAI connection
16    const response = await connections.openai.embeddings.create({
17      input: `${record.title}: ${record.body}`,
18      model: "text-embedding-3-small",
19    });
20    const embedding = response.data[0].embedding;
21
22    // write to the Gadget Logs
23    logger.info({ id: record.id }, "generated product embedding");
24
25    // use the internal API to store vector embedding in Gadget database
26    // on shopifyProduct model
27    await api.internal.shopifyProduct.update(record.id, { embedding });
28  } catch (error) {
29    logger.error({ error }, "error creating embedding");
30  }
31
32  await save(record);
33};
34
35export const onSuccess: ActionOnSuccess = async ({
36  params,
37  record,
38  logger,
39  api,
40  connections,
41}) => {};
42
43export const options: ActionOptions = {
44  actionType: "custom",
45  triggers: {
46    api: true,
47  },
48};

1import { applyParams, save, ActionOptions } from "gadget-server";
2import { preventCrossShopDataAccess } from "gadget-server/shopify";
3
4export const run: ActionRun = async ({ params, record }) => {
5  applyParams(params, record);
6  await preventCrossShopDataAccess(params, record);
7  await save(record);
8};
9
10export const onSuccess: ActionOnSuccess = async ({ record, api }) => {
11  // check to see if the product title or description has changed
12  if (record.changes("title") || record.changes("body")) {
13    // enqueue generateEmbedding action to background action queue
14    await api.enqueue(api.shopifyProduct.generateEmbedding, { id: record.id });
15  }
16};
17
18export const options: ActionOptions = { actionType: "create" };

1export const run: ActionRun = async ({ params, api, connections }) => {
2  // get passed in product ids
3  const { productIds } = params;
4
5  if (!productIds) {
6    throw new Error("productIds is required");
7  }
8
9  const pIds = productIds.map((productId) => productId.split("/").pop()!);
10
11  // generate an embedding for the contents of the current cart
12  let cartContents =
13    "This is a list of product titles and descriptions in a shopping cart. I want to find a product that can be recommended based on the similarity to these products: ";
14  for (let id of pIds) {
15    const product = await api.shopifyProduct.findOne(id, {
16      select: { body: true, title: true },
17    });
18    // get product title and description for each product in cart and add to embedding input
19    cartContents += product.body
20      ? `${product.title}: ${product.body},`
21      : `${product.title},`;
22  }
23
24  // use OpenAI to generate embedding for cart
25  const response = await connections.openai.embeddings.create({
26    input: cartContents,
27    model: "text-embedding-3-small",
28  });
29  const embedding = response.data[0].embedding;
30
31  // find the most closely-related product
32  const productToRecommend = await api.shopifyProduct.findFirst({
33    select: {
34      id: true,
35      title: true,
36      // get variants from related productVariant model
37      variants: {
38        edges: {
39          node: {
40            id: true,
41            price: true,
42          },
43        },
44      },
45      // get image from featured productMedia record
46      featuredMedia: {
47        file: {
48          image: true,
49        },
50      },
51      // get the currency for the shop
52      shop: {
53        currency: true,
54      },
55    },
56    // use cosine similarity sort using the cart content embedding to find closest match
57    sort: {
58      embedding: {
59        cosineSimilarityTo: embedding,
60      },
61    },
62    // filter out products that are already in the cart
63    filter: {
64      id: {
65        notIn: pIds,
66      },
67    },
68  });
69
70  // prep payload for response
71  const { id, title, featuredMedia, variants, shop } = productToRecommend;
72  const currency = shop?.currency;
73
74  // increment offerCount atomically so count is always accurate in db
75  await api.internal.shopifyProduct.update(id, {
76    _atomics: {
77      offerCount: { increment: 1 },
78    },
79  });
80
81  // return the recommendation to the extension
82  return {
83    id,
84    title,
85    imgSrc: (featuredMedia?.file?.image as Record<string, any> | undefined)
86      ?.originalSrc,
87    variant: variants.edges[0].node,
88    currency,
89  };
90};
91
92// define custom param: an array of product ids
93export const params = {
94  productIds: {
95    type: "array",
96    items: {
97      type: "string",
98    },
99  },
100};

1import { AutoTable } from "@gadgetinc/react/auto/polaris";
2import { Card, Layout, Page } from "@shopify/polaris";
3import { api } from "../api";
4
5export default function () {
6  return (
7    <Page title="Products offered in checkout">
8      <Layout>
9        <Layout.Section>
10          <Card>
11            <AutoTable
12              model={api.shopifyProduct}
13              columns={["title", "offerCount"]}
14              initialSort={{ offerCount: "Descending" }}
15              actions={[]}
16              live
17            />
18          </Card>
19        </Layout.Section>
20      </Layout>
21    </Page>
22  );
23}

1import { Client } from "@gadget-client/<YOUR-APP-SLUG>";
2import { useGlobalAction } from "@gadgetinc/react";
3import { Provider, useGadget } from "@gadgetinc/shopify-extensions/react";
4import {
5  Banner,
6  BlockStack,
7  Button,
8  Divider,
9  Heading,
10  Image,
11  InlineLayout,
12  reactExtension,
13  SkeletonImage,
14  SkeletonText,
15  Text,
16  useApi,
17  useApplyCartLinesChange,
18  useCartLines,
19} from "@shopify/ui-extensions-react/checkout";
20import { useEffect, useState } from "react";
21
22// initialize a new Client for your Gadget API
23const client = new Client();
24
25export default reactExtension("purchase.checkout.block.render", () => <GadgetExtension />);
26
27// component to set up the Provider with the sessionToken from Shopify
28function GadgetExtension() {
29  const { sessionToken } = useApi();
30
31  return (
32    <Provider api={client} sessionToken={sessionToken}>
33      <Extension />
34    </Provider>
35  );
36}
37
38function Extension() {
39  const [fetched, setFetched] = useState(false);
40  const [adding, setAdding] = useState(false);
41  const [showError, setShowError] = useState(false);
42
43  // Use `i18n` to format currencies, numbers, and translate strings
44  const { i18n } = useApi();
45  // Get the current state of the cart
46  const cartLines = useCartLines();
47  // Get a reference to the function that will apply changes to the cart lines from the imported hook
48  const applyCartLinesChange = useApplyCartLinesChange();
49
50  // get a 'ready' boolean from the useGadget hook
51  const { ready, api } = useGadget<typeof client>();
52
53  const [{ data: offer, fetching, error: getOfferError }, getOffer] = useGlobalAction(api.recommendProduct);
54
55  // fetch the product to offer with Gadget action call
56  useEffect(() => {
57    const fetchOffer = async () => {
58      const productIds = cartLines.map((cartLine) => cartLine.merchandise.product.id);
59      // call getOffer callback provided by hook
60      await getOffer({ productIds });
61    };
62
63    if (cartLines && !fetched) {
64      setFetched(true);
65      fetchOffer()
66        // make sure to catch any error
67        .catch(console.error);
68    }
69  }, [cartLines, fetched]);
70
71  // If an offer is added and an error occurs, then show some error feedback using a banner
72  useEffect(() => {
73    if (showError) {
74      const timer = setTimeout(() => setShowError(false), 3000);
75      return () => clearTimeout(timer);
76    }
77  }, [showError]);
78
79  // loading state while fetching offer
80  if ((!offer && !getOfferError) || fetching) {
81    return (
82      <BlockStack spacing="loose">
83        <Divider />
84        <Heading level={2}>You might also like</Heading>
85        <BlockStack spacing="loose">
86          <InlineLayout spacing="base" columns={[64, "fill", "auto"]} blockAlignment="center">
87            <SkeletonImage aspectRatio={1} />
88            <BlockStack spacing="none">
89              <SkeletonText inlineSize="large" />
90              <SkeletonText inlineSize="small" />
91            </BlockStack>
92            <Button kind="secondary" disabled={true}>
93              Add
94            </Button>
95          </InlineLayout>
96        </BlockStack>
97      </BlockStack>
98    );
99  }
100
101  // Get the IDs of all product variants in the cart
102  const cartLineProductVariantIds = cartLines.map((item) => item.merchandise.id);
103
104  // check to see if the product is already in the cart
105  const productInCart = cartLineProductVariantIds.includes(`gid://shopify/ProductVariant/${offer.variant.id}`);
106
107  // If the product is in the cart, or there is an error fetching the offer
108  // then don't show the offer
109  if (productInCart || getOfferError) {
110    return null;
111  }
112
113  // Choose the first available product variant on offer
114  const { imgSrc, title, variant, currency } = offer;
115
116  // Localize the currency for international merchants and customers
117  const renderPrice = i18n.formatCurrency(variant.price, { currency });
118
119  // Use the first product image or a placeholder if the product has no images
120  const imageUrl =
121    imgSrc ?? "https://cdn.shopify.com/s/files/1/0533/2089/files/placeholder-images-image_medium.png?format=webp&v=1530129081";
122
123  return (
124    <BlockStack spacing="loose">
125      <Divider />
126      <Heading level={2}>You might also like</Heading>
127      <BlockStack spacing="loose">
128        <InlineLayout
129          spacing="base"
130          // Use the `columns` property to set the width of the columns
131          // Image: column should be 64px wide
132          // BlockStack: column, which contains the title and price, should "fill" all available space
133          // Button: column should "auto" size based on the intrinsic width of the elements
134          columns={[64, "fill", "auto"]}
135          blockAlignment="center"
136        >
137          <Image border="base" borderWidth="base" borderRadius="loose" source={imageUrl} accessibilityDescription={title} aspectRatio={1} />
138          <BlockStack spacing="none">
139            <Text size="medium" emphasis="bold">
140              {title}
141            </Text>
142            <Text appearance="subdued">{renderPrice}</Text>
143          </BlockStack>
144          <Button
145            kind="secondary"
146            loading={adding}
147            accessibilityLabel={`Add ${title} to cart`}
148            onPress={async () => {
149              setAdding(true);
150              // Apply the cart lines change
151              const result = await applyCartLinesChange({
152                type: "addCartLine",
153                merchandiseId: `gid://shopify/ProductVariant/${variant.id}`,
154                quantity: 1,
155              });
156              setAdding(false);
157              if (result.type === "error") {
158                // An error occurred adding the cart line
159                // Verify that you're using a valid product variant ID
160                // For example, 'gid://shopify/ProductVariant/123'
161                setShowError(true);
162                console.error(result.message);
163              }
164            }}
165          >
166            Add
167          </Button>
168        </InlineLayout>
169      </BlockStack>
170      {showError && <Banner status="critical">There was an issue adding this product. Please try again.</Banner>}
171    </BlockStack>
172  );
173}