**Use Case:** After a discovery session, you've understood there are custom solutions necessary to meet the requirements of a desired workflow or process.

**Approach:** *staring blankly at dev docs hoping for a lightbulb moment*

**Problem:** You literally don't know where to start. Even if you did magically find the right path forward, how do you start to illustrate the idea to get others on board with your thinking?

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2F2s2FWWsT8lEnWbjIwKGe%2Fc9352013-d4ea-4ded-9184-91bc4c74c789.png?alt=media&token=cbabcf22-49ca-402f-a368-c585ad770ea6","id":"c9352013-d4ea-4ded-9184-91bc4c74c789","width":4000,"height":2951,"filename":"fullboard_extensibility.png","type":"image/png","caption":"Full brainstorm board for illustrating extensibility APIs","border":false}]}
```

The above board is a full export of a single file I have set up in [Figjam](https://www.figma.com/figjam/) that I've built for the singular purpose of explaining Shopify's [Checkout Extensibility](https://shopify.dev/docs/apps/build/checkout) suite both internally to my team, and externally to merchants and partners.

***Note:** There's nothing proprietary in here - it's almost literally a re-imagining of the public dev docs.*

**But** it didn't start it's life as the library of assets it's turned into - at first, it was a personal board where I visually mapped out the new tools and APIs that I had to learn. The practice of building visuals for the concepts helped sear them into my brain, and it was the first step towards truly being able to teach them to others effectively.

Something I know intrinsically about myself is that I only respond well to information when it's presented beautifully. I resent when I have to stare at some convoluted and ugly chart while also trying to parse the information within it. Anecdotally, I've also found that to be true among wider swaths of people, especially those in large and distributed teams.

The most detailed documentation asset is rarely the one that gets shared the most. The resource that gets the most attention will be the one people *feel good* about sharing with others - and they're more likely to feel that way when the presentation is clean and enjoyable to interact with.

To that end, over the past couple of years I've developed a personal 'design language' that I adhere to. It's multi-purpose:

* Gives me a starting point that's already about %25 of the way done. The framework is already there for me, I just have to fit my ideas into place.

* Allows me to put my own 'stamp' on assets I create, so colleagues know who to contact for more information.

* Keeps my presentations consistent between conversations that might be ongoing for months.

As an example, let's look at a workflow template I have set up for custom checkout process solutions:

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2F2s2FWWsT8lEnWbjIwKGe%2F81a3e033-c157-4e6e-9aa8-d6491e297f2d.png?alt=media&token=062e52f1-b5a5-4dd9-87c0-0e5280447c04","id":"81a3e033-c157-4e6e-9aa8-d6491e297f2d","width":4000,"height":2336,"filename":"solution_template.png","type":"image/png","caption":"Template for developing a solution workflow","border":false}]}
```

I use simple black for primary processes, a black outline for secondary, a big bold colour for tertiary processes, and the same bold colour outline for quaternary. I have options available for fifth, sixth, seventh... if I ever get to eight, I guess I'll just panic.

I've got a little asset I can pull in to illustrate decision trees. Icons are used to illustrate common pieces of the puzzle that I might need to represent. There are even brand logos ready for the most common software and services that may need to be integrated into the workflow, depending on the current tech stack that I need to consider.

(As an aside, this is one reason why I love Figjam for this work. Not only is it flexible as a brainstorming board with a large team, but it has plugins for [icons](https://www.figma.com/community/plugin/1183020129233350982/flaticon-by-freepik) and [company logos](https://www.figma.com/community/plugin/733590967040604714/brandfetch) that I can just pull into my diagrams at any time without needing to leave my space.)

Once more, this is set up so that I can jump *immediately* to brainstorming a solution, without spending any time or effort on defining it's structure.

A very simple final example may look like this, a workflow diagram for pre-selecting a preferred payment method based on customer tags *\[a method worth it's own little post later on\]*:

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2F2s2FWWsT8lEnWbjIwKGe%2F1113992b-fd71-451e-9e55-105c466678b8.png?alt=media&token=e6d9bc30-b7bd-43b1-8c6b-83e49e1aad7c","id":"1113992b-fd71-451e-9e55-105c466678b8","width":4000,"height":1792,"filename":"preselected_payment.png","type":"image/png","caption":"Completed solution workflow built around Template","border":false}]}
```

This works really well for 'swim lane' style workflows like those above, but what about architecture diagrams that have a lot more complexity?

I have an alternate design template for those assets, to be more in line with what's expected in a professional sense from technical diagramming. However, I still like to introduce quality-of-life elements into design to help those less familiar with the concepts grasp what's being presented.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2F2s2FWWsT8lEnWbjIwKGe%2Fe3674f9c-89d9-4f3d-be9c-b31d2cd64b11.png?alt=media&token=f589a90d-fe64-4ab3-8046-8881a9235a81","id":"e3674f9c-89d9-4f3d-be9c-b31d2cd64b11","width":4000,"height":1625,"filename":"example_headless_arch.png","type":"image/png","caption":"Example diagram of a headless architecture on Shopify","border":false}]}
```

A tech stack diagram I'll design typically follows the conventions I've set out in the example above.

Flat, clearly legible in colour or converted to monochrome, with technologies grouped within boxes, while their relationships are contextualised along the process arrows that connect them. Whenever possible, I try to keep it close to a 3:2 aspect ratio, making sure it'll fit neatly within a slide deck or in a document (horizontally).

It's also *highly* modular, so I can reuse pieces across designs whenever the situation calls for it, which is maybe best illustrated by this highly abstract tech stack that I use to introduce total newcomers to the mere concept of what Shopify offers out-of-the-box.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2F2s2FWWsT8lEnWbjIwKGe%2F75603db8-15cb-4f96-936a-d20d73410db5.png?alt=media&token=5b5308ea-321c-46d7-a19f-89573ca31f51","id":"75603db8-15cb-4f96-936a-d20d73410db5","width":4000,"height":1898,"filename":"abstract_tech_stack.png","type":"image/png","caption":"An abstract and generic tech stack highlighting Shopify","border":false}]}
```

This diagram could become vastly more complex just by adding more detail into the downstream and peripheral integrations that would feed the various services in place. It could also become much simpler by removing pieces that I know the solution doesn't require and culling detail from what Shopify offers (eg. just listing `products`, `orders`, and `customers` in the 'Backend' section if that's all the business cares about storing in Shopify).

I like including icons representing each box to clearly identify the category of each piece, and to help fill blank space where necessary. I can also subtly convey suggestions through logos, such as the common hosting platforms I've listed alongside the 'Self Hosted' box in the top-left corner.

If I'm tailoring it specifically to a business' existing tech stack, I'll often re-create the diagram they provide me and incorporate my re-build of their stack into my own additions. (If they haven't provided me a diagram to reference, I'll use what I learned from discovery to approximate a best guess of data flow.)

Over time, similar to the workflow templates, I've developed a generic file to begin with for tech stack illustrations, so that I very rarely have to go looking for logos and icons to represent various services and technologies specific to the solution.

**Summary:**

* People connect with ideas they can see and easily understand. Supplement your writing with clear visuals that everyone can share.

* Eliminate your 'writers block' by developing templates that structure your brainstorming sessions.

* Prioritise re-usability into every asset you create, not just for you, but to provide your team with good resources when you inevitably move onto new challenges.

✌️

Designing Solution Workflows

**Use Case:** A Shopify Multi-Currency enabled store using Markets has a lightweight 'Membership' program where a secondary price is provided to logged-in customers with an active membership state. \
\
**Approach:** A Cart Transform Function is handling an adjustment to the cart & checkout price of a product based on a metafield value. The Function's logic applies a currency adjustment to the metafield value to account for multi-currency scenarios. I also want to show that metafield value as a secondary price on the PDP, also accounting for the currency conversion of that value to match the cart & checkout price as calculated by the Function.

**Problem:** Liquid cannot easily access the same 'presentmentCurrencyRate' field that's accessible via the Functions API.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2F6dFziEBYnpyiwdauRosO%2Fc733ae83-3624-4ffd-866d-5a39618681a0.png?alt=media&token=e3ceb990-cc9f-4b68-afa3-a15f6e3fdcfc","id":"c733ae83-3624-4ffd-866d-5a39618681a0","width":3024,"height":1504,"filename":"Screenshot 2024-07-11 at 11.34.16.png","type":"image/png","caption":"","border":false}]}
```

I ran into this problem recently, and it had me stuck at a strange dead-end I didn't expect. My Cart Transform function was working perfectly, returning a `fixedPricePerUnit` that properly accounts for multi-currency scenarios by modifying a Metafield value by the cart's current `presentmentCurrencyRate`.

```jsx
function optionallyBuildUpdateOperation(
 { id: cartLineId, merchandise },
 presentmentCurrencyRate
) {
 if (
 merchandise.__typename === "ProductVariant" &&
 merchandise.product &&
 merchandise.product.metafield &&
 merchandise.product.metafield.value
 ) {
 return {
 cartLineId,
 price: {
 adjustment: {
 fixedPricePerUnit: {
 amount: Number(merchandise.product.metafield.value) * Number(presentmentCurrencyRate)
 }
 }
 }
 };
 }

 return null;
}
```

And I had a really simple Liquid snippet in the PDP template that pulled in the same `member_price` metafield to show the customer what they can expect when compared to the non-member regular price:

```
{% if product.metafields.custom.member_price %} Member Price:{{ product.metafields.custom.member_price }} {% endif %}
```

But when that's in place, we obviously get a strange mismatch for other regions where the `member_price` is a value set in the shops' base currency and isn't adjusted for the active market.

One solution could presumably be to store multiple `member_price` metafields that are all individually adjusted per region, like `member_price_uk` + `member_price_us`, etc.

But if we consider that larger businesses are most likely feeding their price maps to Shopify via the Product API from a PIM or other source of truth, that's getting pretty complex very quickly and waters down data quality over time. I like the relative security of letting the Store's configured currency rates in Markets settings determine the conversion as opposed to multiple hard-coded prices.

So another possible solution is to use Shopify's provided .js file with live currency conversion rates to return a value to my liquid snippet based on the active country code.

```
/services/javascripts/currencies.js
```

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2F6dFziEBYnpyiwdauRosO%2Faf2fc529-ba4f-4f16-ad50-1a1ee867adc7.png?alt=media&token=07e3436e-f51a-407c-bd6e-6dd791376f34","id":"af2fc529-ba4f-4f16-ad50-1a1ee867adc7","width":3024,"height":688,"filename":"Screenshot 2024-07-11 at 11.42.06.png","type":"image/png","caption":"","border":false}]}
```

This seemed like overkill to me. Also, I didn't love the idea of modifying the price.liquid base snippet and pulling in a bunch of live rates the store might not even use. Larger businesses are much more likely to set static conversion rates that suit their needs, which mirrors what I have set up in my Demo store.

eg. USD = x1.3, EUR = x1.5, CAD = x1.8

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2F6dFziEBYnpyiwdauRosO%2F9584640d-7b4e-4d16-b688-7082a0456157.png?alt=media&token=26a6060c-b5f6-4e3f-98a5-6f402f54b523","id":"9584640d-7b4e-4d16-b688-7082a0456157","width":2028,"height":1060,"filename":"Screenshot 2024-07-11 at 11.51.24.png","type":"image/png","caption":"","border":false}]}
```

Okay, so now that we know the rates are fine as static conversion, we can do some simpler things just within my liquid snippet. Shopify gives us the active market through Liquid with the localization object:

```
localization.market.handle
```

That should mirror what the Cart Transform is accessing as the presentmentCurrencyRate -- as long as the Market has a static currency rate across all the regions it serves (which is luckily a lot more common than showing prices in the customer's local currency).

So now I can assign the market to a specific converted price that I define in the liquid snippet:

```
{% assign market_handle = localization.market.handle %}

{% if product.metafields.custom.member_price %}
 {% assign member_price = product.metafields.custom.member_price %}
 
 {% if market_handle == 'north-america' %}
 {% assign converted_price = member_price | times: 1.3 %}
 {% elsif market_handle == 'europe' %}
 {% assign converted_price = member_price | times: 1.5 %}
 {% elsif market_handle == 'canada' %}
 {% assign converted_price = member_price | times: 1.8 %}
 {% else %}
 {% assign converted_price = member_price %}
 {% endif %}
 
 Member Price:{{ converted_price | money_with_currency }}
{% endif %}
```

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2F6dFziEBYnpyiwdauRosO%2F551efd89-f07f-4147-a4c2-246f5468134e.png?alt=media&token=cadd06b5-1946-4a17-846b-2e0f92daf49c","id":"551efd89-f07f-4147-a4c2-246f5468134e","width":3024,"height":1510,"filename":"Screenshot 2024-07-11 at 12.04.07.png","type":"image/png","caption":"","border":false}]}
```

***Sweet.*** That's better.

Now if the shop ever wants to adjust their hard-coded currency conversion rates, they can do that much more easily just within a Liquid snippet in the Theme Editor, as opposed to within the theme code itself.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2F6dFziEBYnpyiwdauRosO%2Fd2a3a7c1-c200-429a-8333-412ffbfd8f45.png?alt=media&token=709652e2-76a4-4614-982c-3f723f4cea58","id":"d2a3a7c1-c200-429a-8333-412ffbfd8f45","width":2888,"height":1418,"filename":"Screenshot 2024-07-11 at 12.09.35.png","type":"image/png","caption":"","border":false}]}
```

If you want to see the full Cart Transform Function code for this app that's essentially a lightweight membership program, I have it public here:

[Github - Mackiec Extensions Prod - Update Line Item](https://github.com/mackiec/mackiec-extensions-prod/tree/main/extensions/update-line-item-js)

✌️

Currency Adjusted Metafield with Liquid

**Use Case:** A product or service requires some customer-provided instructions for special considerations related to their cart (eg. hard-to-find address, delivery difficulties for heavy items, etc.)

**Approach:** Shopify's Checkout UI Extensions has pre-built components for text entry within the Checkout sections, which can take customer input as a string.

**Problem:** Providing extra delivery instructions for every checkout could introduce some customer confusion and negatively impact conversion rates. Only certain conditions of the cart should prompt the customer for more information, and those extra details need to be stored on the resulting order for a 3PL/WMS/OMS to use for fulfilment.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2FQZdFPZ2Cz5bbGYvOpAnS%2F1a2d2f56-129b-4c89-bebc-ba0204897f3f.gif?alt=media&token=8bc217ca-93b6-4c95-b31f-0a830c7d1860","id":"1a2d2f56-129b-4c89-bebc-ba0204897f3f","width":800,"height":494,"filename":"ezgif-5-db8d7716c5.gif","type":"image/gif","caption":"Conditional delivery instructions when Address 2 is provided","border":false}]}
```

This extension started a personal little addition to a dev site where I'm experimenting with Checkout UI APIs. Initially, I'd just implemented Shopify's standard [Delivery Date Picker](https://shopify.dev/docs/apps/build/checkout/delivery-shipping/delivery-methods/date-picker), but I needed a demo that expanded on the idea of a date picker and allowed for more context to be provided by a customer once a date had been chosen.

Going one step further, I figured I'd make it even more conditional by adding in a few rules:

* The 'Date Picker' Calendar is only displayed when a product features a specific `show_date_picker` boolean metafield (instead of the .dev example, which is tied to chosen Shipping Rate).

* Extra delivery instructions can **only** appear when two things are true: an `address2` field is present, *and* a delivery date has been picked.

One more thing needs to happen to round out the solution; write the delivery instructions input back to a metafield on the Order to actually use the result in a fulfilment workflow. Otherwise, it was a nice afternoon spent in VSCode for absolutely no useful reason (*story of my life*).

Ultimately, this is our customer view in Checkout, and then the output on the completed order:

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2FQZdFPZ2Cz5bbGYvOpAnS%2F4b2bfca2-d09e-440e-9ca6-8e9ff57c9c06.png?alt=media&token=8a12ce1d-a55c-44cb-b033-100b5e7c4b5d","id":"4b2bfca2-d09e-440e-9ca6-8e9ff57c9c06","width":2060,"height":1332,"filename":"Screenshot 2024-08-29 at 15.19.51.png","type":"image/png","caption":"Customer view in Checkout of Delivery Picker & Instructions","border":false}]}
```

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2FQZdFPZ2Cz5bbGYvOpAnS%2F6b621962-c9d2-4d96-9b16-dcec17737ae4.png?alt=media&token=f46814cf-2043-49fa-8d47-4685b5506375","id":"6b621962-c9d2-4d96-9b16-dcec17737ae4","width":2060,"height":1332,"filename":"Screenshot 2024-08-29 at 15.20.14.png","type":"image/png","caption":"Merchant view of completed Order with Delivery Metafields","border":false}]}
```

Surprisingly, the whole 'Delivery Instructions' module is less than 100 lines of code. It could be simplified even further, because I've made some UX choices that are optional. One could argue you probably don't need the 'checkbox' condition that expands the text field input, but I felt like an auto-expanded instructions textfield was a little presumptuous, as if it was asking to be filled out even if there was no need. Customers don't need to see an empty box that clutters their experience - our priority should be to get them through the Checkout quickly and without annoying them.

I'm also including some quality-of-life improvements here:

* If 'Delivery Instructions' were provided by a customer, but then they changed their mind and unchecked the box (leaving their instructions), then the extension deletes the metafield that's been set on the Checkout.

* The text field is multi-line by default, but doesn't have to be - a single line is probably sufficent.

* Fancy icons and spacing elements from the Shopify Component Library.

Here is my `Checkout.jsx` file in it's entirety for this extension:

```jsx
import React, { useState } from "react";
import {
 reactExtension,
 TextField,
 BlockStack,
 useApplyMetafieldsChange,
 useMetafield,
 Checkbox,
 Text,
 Banner,
 BlockSpacer,
 InlineLayout,
 Icon,
 View,
 useShippingAddress,
} from "@shopify/ui-extensions-react/checkout";

// Set the entry point for the extension
export default reactExtension("purchase.checkout.shipping-option-list.render-after", () => {
 return <App />;
});

function App() {
 // Set up the checkbox state
 const [checked, setChecked] = useState(false);

 // Define the metafield namespace and key
 const metafieldNamespace = "custom";
 const metafieldKey = "delivery_instructions";

 // Get a reference to the metafield
 const deliveryInstructions = useMetafield({
 namespace: metafieldNamespace,
 key: metafieldKey,
 });
 // Set a function to handle updating a metafield
 const applyMetafieldsChange = useApplyMetafieldsChange();

 // Get the shipping address
 const shippingAddress = useShippingAddress();

 // Check if 'address2' is provided in the Shipping Address form
 const hasAddress2 = shippingAddress && shippingAddress.address2;

// Handle when the checkbox is checked. 
 // If the checkbox is unchecked by the buyer, unset (delete) the metafield
 const handleCheckboxChange = (isChecked) => {
 setChecked(isChecked);
 if (!isChecked) {
 updateMetafield({
 type: "removeMetafield",
 namespace: METAFIELD_NAMESPACE,
 key: METAFIELD_KEY,
 });
 }
 };

 // Render the extension components
 return (
 <BlockStack>
 {hasAddress2 && (
 <View maxInlineSize={700}>
 <Banner status="info">
 <InlineLayout blockAlignment="center" spacing="small100" columns={['auto', 'fill']}> 
 <Icon source="note" appearance="monochrome"></Icon>
 <Text size="medium" appearance="accent" emphasis="bold">
 Add Delivery Instructions?
 </Text>
 </InlineLayout>
 <BlockSpacer spacing="loose" />
 <Checkbox checked={checked} onChange={handleCheckboxChange}>
 <Text>Yes, please see details:</Text>
 </Checkbox>
 
 {checked && (
 <>
 <BlockSpacer spacing="loose" />
 <TextField
 label="Add Your Delivery Instructions"
 multiline={3}
 onChange={(value) => {
 // Apply the change to the metafield
 applyMetafieldsChange({
 type: "updateMetafield",
 namespace: metafieldNamespace,
 key: metafieldKey,
 valueType: "string",
 value,
 });
 }}
 value={deliveryInstructions?.value}
 />
 </>
 )}
 </Banner>
 </View>
 )}
 </BlockStack>
 );
}
```

**Note:** Publishing this via an extension-only app does not auto-create the metafield definition for the shop. You'll need to create the `custom.delivery_instructions` (or the namespace and key of your choice) metafield within a store's admin for the extension to apply it's values properly to an order.

Thinking out loud, this has potential changes you could make here to address an additional use cases:

**Allergy Substitutions Instructions at Checkout:**

* Allow a customer to provide their allergens in a profile customisation, store those allergens in a Customer Metafield.

* Store ingredient details on products, also using metafield(s) (could be [a list, or a JSON array](https://shopify.dev/docs/apps/build/custom-data/metafields/list-of-data-types)).

* Re-Configure the above extension to look for any matching metafields between the logged-in Customer's allergens, and the ingredients lists of the products within their cart.

* Warn them of potential issues, and surface the 'Instructions' text field to allow them to specify any substitutions to make before delivery.

* *\[Optional\]* [Block checkout progress](https://shopify.dev/docs/api/checkout-ui-extensions/unstable/configuration#block-progress) via the same extension until they provide substitutions so you don't have a lawsuit on your hands.

Here's an example of discovering a boolean true/false product metafield of `custom.show_allergy_substitutions` via the UI extension to decide whether or not to return an instructions element:

```jsx
// Check if any product in the cart has the show_allergy_substitutions metafield set to true
 useEffect(() => {
 for (const cartLine of cartLines) {
 const product = cartLine.merchandise.product;
 product.id = String(product.id.match(/(\d+)$/)[0]);
 for (const metafieldEntry of appMetafields) {
 if (
 metafieldEntry.target.type === "product" &&
 metafieldEntry.target.id === product.id &&
 metafieldEntry.metafield.namespace === "custom" &&
 metafieldEntry.metafield.key === "show_allergy_substitutions" &&
 metafieldEntry.metafield.value === "true"
 ) {
 setHasShowAllergySubsMetafield("true");
 break;
 }
 }
 if (hasShowAllergySubsMetafield === "true") {
 break;
 }
 }
 }, [cartLines, appMetafields, hasShowAllergySubsMetafield]);
```

I'd love to hear any other use cases you can think of! Contact me either though my website at [www.mackiec.ca](https://www.mackiec.ca/contact), or on the [Shopify Partners Slack](https://shopifypartners.slack.com/join/shared_invite/zt-sdr2quab-mGkzkttZ2hnVm0~8noSyvw#/shared-invite/email)

**Summary:**

Checkout UI Extensions can be nested behind conditions of the cart (including product or customer metafields) to only be served when it makes the most contextual sense for the business. Prioritise conversion speed and only bring forward UI elements for the customers who absolutely need to see them.

✌️

Conditional Delivery Instructions Input

**Use Case:** An external data source holds relevant information that needs to be served to the Checkout to inform a transactional or business process.

**Approach:** *In this example*, an external source holds customer membership information that is able to adjust the base price of one or more line items accordingly. This data informing the customer membership must be held offsite, because multiple selling channels sync to a central source of customer truth. Not all customers with status will have an active 'Online Store' account, but still expect their membership to apply price adjustments when they first visit the website.

**Problem:** Cart Transform Functions or Discount Functions that can modify line item prices do not have external network access outside [very specific circumstances](https://shopify.dev/docs/apps/build/functions/input-output/network-access#:~:text=Network%20access%20for%20Shopify%20Functions%20allows%20you%20to%20configure%20HTTP,merchants%20on%20Shopify%20for%20enterprises.). However, Checkout UI Extensions have the ability to request [Network Access](https://shopify.dev/docs/api/checkout-ui-extensions/2024-04/configuration#network-access), which can handle the retrieval of external data based on provided details.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2Finform-shopify-functions%2Fe222e79b-3c21-413a-b680-0d1c8b04a8a8.png?alt=media&token=bd499ef8-89d5-4226-9156-aa5842636680","id":"e222e79b-3c21-413a-b680-0d1c8b04a8a8","width":2400,"height":1278,"filename":"normal.png","type":"image/png","caption":"","border":false}]}
```

I often show this simple workflow diagram to help visualise the Extensibility tools available within the Checkout, and I'm starting the realise that the arrows are under-explained. Using the strengths of each aspect independently can solve a more complex problem than any one application can solve on it's own.

The idea is that you initiate an action, which creates a unique event, which sets off another action, which creates a unique event, etc. I call it the Rube Goldberg approach to solutions.

In a truly ideal state, you're always using data that you're already storing within Shopify to use in your Functions' input queries, because it's simply faster and more reliable. *But*, what if the object you'd store your data in **doesn't exist yet**, so it's not available to query? Like a retail customer who might be known to other systems, but not to Shopify (yet)?

Here's a quick but critical adjustment to the flow to help us visualise:

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2Finform-shopify-functions%2F3e5d57f0-e907-47ea-a4fd-c4350255f1bb.png?alt=media&token=f991ec4b-addf-400c-98ad-697bc2f9f7c8","id":"3e5d57f0-e907-47ea-a4fd-c4350255f1bb","width":3088,"height":1339,"filename":"external_fetch.png","type":"image/png","caption":"","border":false}]}
```

Because Shopify re-executes Functions and re-renders Extensions when the Cart Object is updated, we can set up a 'cause and effect' process to benefit complex decision making in the checkout. This is where we can to get a little creative with introducing a new connection to our flow; a UI Extension can bring in external data from an available endpoint, and then [apply a Cart Attribute](https://shopify.dev/docs/api/checkout-ui-extensions/2024-07/apis/attributes#checkoutapi-propertydetail-applyattributechange) to the Checkout to 'store' it in Shopify and update the cart object, which makes it available [for a Function to use](https://shopify.dev/docs/api/functions/reference/cart-transform/graphql/common-objects/cart#attribute-2024-07).

*eg. Use a UI Extension to take a unique input from a customer, retrieve external data based on the input, update the cart object with a unique attribute as a result, which executes a Function that's looking for that unique attribute.*

If we stick with our example: I want to give a 10% discount for registered customers who might be known to me through other channels, but it's their first time shopping online.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2FRTCEFm02dEkiDin3g2FR%2F2c2e2d2d-8be8-4771-94ff-61f0ed03fde6.png?alt=media&token=53c51ef3-4672-4259-8fd2-e33eed588b8e","id":"2c2e2d2d-8be8-4771-94ff-61f0ed03fde6","width":1246,"height":690,"filename":"Screenshot 2024-07-15 at 14.38.22.png","type":"image/png","caption":"","border":false}]}
```

Using a [custom text field](https://shopify.dev/docs/api/checkout-ui-extensions/2024-04/components/forms/textfield) entry enables us to take a membership 'number' as the very first step of the checkout, which can make it's [external network call](https://shopify.dev/docs/api/checkout-ui-extensions/2024-04/configuration#network-access) to fetch membership data from an available endpoint in our customer source of truth. Once our data's fetched, the `applyAttributeChange` mutation available [via the CheckoutAPI through UI Extensions](https://shopify.dev/docs/api/checkout-ui-extensions/2024-04/apis/attributes#checkoutapi) attaches an attribute to the Checkout specifying the member's details have been checked.

A price modification such as a Discount Function can be configured to that applied checkout attribute into it's input query.

```graphql
run.graphql

query RunInput {
  cart {
    attribute(key: "member_valid") {
      value
    }
  }
}
```

And then we can configure the run.js to use that unique cart attribute to trigger wether or not a discount should be applied. If there is no `memberValidAttribute` found, no Discount is applied.

```jsx
run.js

// @ts-check
import { DiscountApplicationStrategy } from '../generated/api';

const EMPTY_DISCOUNT = {
  discountApplicationStrategy: DiscountApplicationStrategy.First,
  discounts: [],
};

export function run(input) {
  const { cart } = input;

  // Check for the 'member_valid' attribute
  const memberValidAttribute = input?.cart?.attribute?.key === 'member_valid';

  if (!memberValidAttribute) {
    return EMPTY_DISCOUNT;
  }

  return {
    discounts: [
      {
        value: {
          percentage: {
            value: 10,
          },
        },
        targets: [
          {
            orderSubtotal: {},
          },
        ],
      },
    ],
    discountApplicationStrategy: DiscountApplicationStrategy.First,
  };
}
```

Yes - the Discount function will initially execute on checkout creation prior to the Checkout UI Extension setting the attribute, but as long as it's configured to have no result until it gets the data it needs, it'll just sit idly by not doing anything until the checkout changes.

It might end up looking something like this workflow:

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2Finform-shopify-functions%2F709262f8-6bcc-47b4-8014-ae9bd83ae6e7.png?alt=media&token=7505d219-fe37-478b-acaf-4684237ceb57","id":"709262f8-6bcc-47b4-8014-ae9bd83ae6e7","width":4624,"height":2402,"filename":"price change.png","type":"image/png","caption":"","border":false}]}
```

**Considerations:** A fairly major callout here is that Checkout UI Extensions run client-side, so passing sensitive data back as checkout attributes is a really bad idea. Someone who knows what they're doing could fairly easily set their own attribute, triggering any Function configured to look for that data. For example, I'd never fetch an external price for a line item via network access, and then use it as an attribute for a Cart Transform function to operate on. Theoretically, someone could set their own prices in that workflow.

Additionally, as mentioned, it'll always be more reasonable to store custom data informing a Function within Shopify proper - so once the object (such as a customer) exists, a private app should be updating that resource via the Admin API with the necessary data to mirror it with an external source.

A lot of sample extension apps are available publicly here:

[Github - Shopify - Official Function Example Apps](https://github.com/Shopify/function-examples)

✌️

Informing Shopify Functions via UI External Network Access

Open for collaborations anytime! Find me on Insta at @mackiec or on my website at www.mackiec.ca

Photographer

An experimental online gallery that mimics the experience of sequencing physical 4x6 prints on a tabletop. The series is comprised of 37 images.

Viewers can 'discard' images by throwing them offscreen, choose to pile their favourites, or sequence their own unique set.

Developed using html, css, and javascript, the project is a lightweight application blending art and technology for a new interactive approach to exploring a set of images on a webpage.

Images featured are all analog frames captured in Japan throughout Tokyo, Kyoto, and Osaka, using a Leica M6 with 35mm Kodak Portra and Cinestill films.\
\
<https://www.mackiec.ca/japan-4x6-project>

JAPAN 4x6 PROJECT

This project is an attempt to understand what I have seen since moving as an expat to the United Kingdom. I have seen vignettes of detestable greyness, and then vibrant beauty - often within the same hour. How can one place be so different, all the time?

The 40 images featured within are circumstantial juxtapositions, with each new page providing a kindred narrative to the other. A couple walks their dog up an incline overlooking the sea, while people busily walk down a sun-patched incline in the city. Friends ride fake horses in a field next to a parking lot, while a girl swims her real one at the beach.

We all must find what we like.

\---

A5 \[210mm x 148mm\]\
44 Pages\
Paper: 170 GSM - Uncoated\
Cover: 350 GSM - Recycled Silk\
Digital Printed\
Stapled

WE FIND WHAT WE LIKE

Across 5 years of travel throughout the UK and the EU, a familiar scene of people finding their way around began to catch my attention as a meaningful part of a single day's journey. We can be so hesitant to ask for help, especially if it reveals us to be vulnerable in any way. To admit that one is lost is a doubling-down on admitting our helplessness.

In these 33 images, we see couples finding their way through the world together, individuals identifying their place in the world, and strangers being asked for their directional advice.

All of it shines a light on our blind spots and helps us to understand the path forward, however winding it might be.

\
\---

A5 \[210mm x 148mm\]\
36 Pages\
Paper: 170 GSM - Uncoated\
Cover: 350 GSM - Recycled Silk\
Digital Printed\
Stapled

WHERE ARE WE GOING

Engaging in both pre-sales and post-sales technical fit validation processes, and resolving strategic puzzles for enterprise or complex key accounts. I help define requirements, and plan workable solutions to achieve a better product for everyone. Subject matter expertise in Shopify's GraphQL & Rest APIs, Extensibility, and general tech stack architecture.

Christian Mackie

Projects

Work Experience

Contact