**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:** Modification or customisations of an order must be completed *prior* to Checkout stage, however the regular purchasing experience of a customer should not be impacted.

**Approach:** Using Draft Orders through Shopify provides the bespoke 'custom order' requirements and business flexibility that we need, with custom line items and opportunity to adjust prices, line items, discounts and other variables at will.

**Problem:** Draft Orders can only be built manually by customer service agents, or programatically via the GraphQL API through an application. The customer also needs access to the generated 'Invoice URL' after Draft Order creation.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2FJKnJo2U2DRw58rphg0vC%2F58171421-0491-4bd7-a89f-d8e1c9ec8e42.png?alt=media&token=ee201535-19fe-45b5-bc98-72ca58e3ced1","id":"58171421-0491-4bd7-a89f-d8e1c9ec8e42","width":7719,"height":3103,"filename":"Build Draft Order From Cart Data.png","type":"image/png","caption":"Using the Draft Order API to generate bespoke checkouts.","border":false}]}
```

Not too long ago, prior to the [Cart Transform API](https://shopify.dev/docs/api/functions/reference/cart-transform) becoming available, it was fairly difficult to allow Customers to directly build 'custom' orders via the storefront and have those changes carry through to Checkout. You could leverage a 3rd Party App that built custom products/carts, or maybe use the [cart.js](https://shopify.dev/docs/api/ajax/reference/cart) to add/remove products and variants that were 'hidden' from regular view, but both had significant drawbacks in both maintenance and scalability. At any business level, the cart is one thing you really shouldn't be playing fast and loose with, arguably the crux of the purchase journey.

Around 2021, pre-Checkout Extensibility, I spoke to a (very) large D2C merchant in the UK about their unique approach towards providing free 'gifts' when an order met certain conditions, and they taught me this methodology which I'd genuinely never considered until then -- using Draft Orders' innate 'Invoice Link' feature as a replacement for the regular Checkout Flow.

As outlined in the above workflow, the steps are roughly:

* Allow a customer to create and interact with their cart as normal. Guest or Logged In, the state of the customer doesn't matter.

* In the background, have an app subscribed to `carts/create` and `carts/update` events via Webhooks.

* Have each `carts/create` event trigger a GraphQL API call to build a new DraftOrder for each new cart.

* Ensure cart session data is mapped and attributed to the created DraftOrder for later recall -- if it's also attached to a logged in customer, even better. Store this attribution in the DraftOrder and/or app managing carts.

* If the customer or cart meets any conditions that require you to customise the order in some way (eg. modify pricing, attach extra products, add custom line items, etc.) then do so via the GraphQL API to the DraftOrder object in the background via the app.

* Through a customised cart in the theme, remove the standard redirect from Cart to Checkout from any available customer actions. Instead, on purchase action click, make a call to the app handling carts and retrieve the Draft Order `invoiceUrl` parameter from the open Draft Order associated with the session.

* Pass that URL back to the storefront and redirect the customer to their unique `invoiceURL` to complete the DraftOrder through the same checkout process they expect.

When done properly, this looks like nothing at all to the customer. If you pair your API-initiated changes with visual changes to the storefront cart, (such as showing them they've reached a threshold and unlocked an upgrade or free item, etc.) then there is no tangible difference to their purchasing experience.

I thought for a little while about how best to show this in practice, and came up with a very low-fi example. No app, no session management, no api call to draft orders. Just three buttons on the cart, all doing different things:

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2FJKnJo2U2DRw58rphg0vC%2F4ad7d830-ad4d-472d-8f6d-aeee0a0edcf2.gif?alt=media&token=96e4a980-8828-4844-81ea-65d5aca4b435","id":"4ad7d830-ad4d-472d-8f6d-aeee0a0edcf2","width":800,"height":474,"filename":"ezgif-3-553186f96b.gif","type":"image/gif","caption":"Three checkout buttons, three different results.","border":false}]}
```

* The first button clicked is the standard, expected 'Checkout' button at the cart. It brings me exactly to the cart I've defined as a customer.

* The second button clicked is a very simple empty draft order that features just a custom line item with a custom price. No customer account attached, no discount, no other products.

* The third button clicked is a more fleshed-out draft order, with a customer attached, a custom line item, and a custom discount on that line item with an explanation as to why it's applied.

In this case, I'm just hard-coding a Draft Order invoice link to each button via the Theme Editor for example purposes, but try to imagine if the original/regular cart button was having it's redirection dynamically served depending on the conditions of the cart. Because the customer never sees the actual invoice link, they simply understand that they are being sent through to the Checkout.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2Falternative-checkout-custom-orders%2F1c8832f9-0919-485a-9c17-a7d18903c4ac.png?alt=media&token=b91428f3-418a-4502-8581-16fcbf4a7719","id":"1c8832f9-0919-485a-9c17-a7d18903c4ac","width":1866,"height":1152,"filename":"Screenshot 2024-10-02 at 16.19.32.png","type":"image/png","caption":"The Draft Order Invoice URL as seen in the object JSON","border":false}]}
```

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2Falternative-checkout-custom-orders%2Fcb64b272-a21f-470b-873b-242938b20a0e.png?alt=media&token=241ca8e2-f71e-4a51-9082-f352fda25d24","id":"cb64b272-a21f-470b-873b-242938b20a0e","width":2332,"height":1278,"filename":"Screenshot 2024-10-02 at 16.19.53.png","type":"image/png","caption":"Hardcoding a button with an invoice link ( ... do not do this!)","border":false}]}
```

There are a lot of quality of life things you can and should do here to make the experience better. It'd be a pretty jarring experience for example, if a customer got through to the invoice checkout, then backed out to the storefront and no longer saw your custom additions/changes reflected in their cart. Implementing a cart modification to mirror the Draft Order you've assigned to the customer would be a good idea, showing the additional items/discounts, etc.

Validation protections should be carefully implemented to ensure Invoices with customer accounts pre-attached are sent to the **correct** customer, and only when that customer has been verified as **logged in**.

One of the main reasons I like this approach is because it results in a regular ol' Shopify-created Order object when the customer completes their invoice checkout. Nothing downstream in other external systems has to change to accommodate this purchasing approach, as far as they're concerned, it's an order like any other.

It's relatively scalable too, as it uses Shopify's Webhooks and Checkout systems to do the bulk of the work. The one caveat I might call out is that at extremely high traffic periods (eg. a BFCM scenario), I have seen 3rd party apps that aren't scaled enough buckle under the volume of cart webhooks that Shopify can potentially send. Every app likes to say they can auto-scale, but trust me, they always overestimate their own resilience compared to Shopify's ability to scale. Subscribing to `carts/update` especially shouldn't be taken lightly, as active customers on a site could easily be updating their carts dozens of times per session, quickly ballooning the events you're intaking.

A reminder going back to the beginning - this was an active and working solution for an above hundred-million dollar brand just a few years ago, and while I'd now replace their use case with a Cart Transform application, it is still a production-tested workflow. Not saying I wouldn't change some things, but it's worth re-establishing!

I'd love to hear what other applications you might imagine, given this approach. Give me shout if you think of something to add or consider!

✌️

Alternative Checkout for Custom Orders

**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%2Fdelivery-instructions-input%2F365e5a9c-0b1a-4965-8281-6392835db2db.png?alt=media&token=9b6e62d5-437e-4c44-8d2c-21124efe6cb5","id":"365e5a9c-0b1a-4965-8281-6392835db2db","width":2048,"height":1324,"filename":"6b621962-c9d2-4d96-9b16-dcec17737ae4.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 list(s) 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.

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

**Use Case:** Product prices are conditional based on a customer's declaration/input that's made during the checkout.

*\[EG. embroidery/engraving is chosen for a product, eat-in markup on prices for restaurants, tax exclusion for non-residents, etc.\]*

**Approach:** When the checkout meets the appropriate conditions, we need to surface a UI Extension featuring the relevant fields for the customer to engage with. Modifying the product prices must be done via a Cart Transform Function, as the displayed prices can't be a strikethrough discount - the actual line item price has to change.

**Problem:** We must pass a cart attribute variable from the UI Extension to the Function input in order for the scenario to actually work. A UI Extension on it's own can't modify pricing, and a Function on it's own can't access states within the section-rendered custom UI Extension.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2FY9cDomNn0JqUkpmWkQdQ%2Fbb09c4e5-d3dc-4f4d-ba12-a51d19135d99.png?alt=media&token=235aa8cd-875a-44a0-9929-fb9b781d021f","id":"bb09c4e5-d3dc-4f4d-ba12-a51d19135d99","width":8154,"height":2938,"filename":"transformpricesforembroidery.png","type":"image/png","caption":"Defining a logic tree before setting off on a build.","border":false}]}
```

Let's take the really typical use case of providing engraving as our baseline here, while keeping in mind how many other applications this solution has available to explore.

I've [written before](https://mackiec.read.cv/inform-shopify-functions) about storing an attribute at Checkout for a Function to read in it's input query and execute it's logic, but in this case I'm going to look specifically at customer-supplied logic within the Checkout to modify pricing.

The workflow example above is based off a real-life scenario with some confusing requirements that I had to design around, which involved taking into account the conditions of a customer's checkout to decide when to show or not show a specific UI element. In this case, I've standardised it to a different use case, but the essential logic flow remains the same;

```
condition > check > condition > check > selected state > output result
```

Keeping a simple visualisation of this logic in my back pocket at all times is mostly to make my own life easier, but it can also help others [grasp the desired outcome of the solution before you set off on a build](https://mackiec.read.cv/designing-solution-workflows).

So let's take a look at the final working version of this logic before I break down how I've implemented it:

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2FY9cDomNn0JqUkpmWkQdQ%2F81624b6b-03db-483f-aa69-068c8df5af12.gif?alt=media&token=58918399-982d-48bb-bf17-2ef86b83371f","id":"81624b6b-03db-483f-aa69-068c8df5af12","width":800,"height":532,"filename":"ezgif-2-cb8442a29e.gif","type":"image/gif","caption":"Providing custom text and modifying the price of an item.","border":false}]}
```

* **IF** the Beanie product is in the cart, a custom checkbox UI is rendered to show that it can be embroidered.

* Then, **IF** the customer selects to add the custom embroidery, two things happen;

* A new UI is surfaced with a custom text entry field.

* *and* the line item price is increased by %10

Our first task should be to build the Extension UI in order to properly set some cart line item attributes that we'll use later in our Function code.

*\[Editor's Note: This step was **much harder** than I expected, because I kept finding new UX things to consider - I'll skip over explaining things like character count, surfacing the textfield based on checkbox state, and the structural components just for time's sake. whew -- but it looks nice!\]*

I wanted to make sure that the UI only displayed under the line items in the cart, and not just anywhere on the page. That's simply handled by the [Extension Target](https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/apis/extensiontargets) of:

`purchase.checkout.cart-line-item.render-after`

Once we've told the UI to only render after each line item, we gotta limit it even more to **only** render for specific products, in this case with the type `Accessories`. Luckily, we can do this right in the `Checkout.jsx` file just through the [CartLineItemAPI object](https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/apis/cartlineitemapi) available to extensions that are using the cart-line-item target we set earlier.

```javascript
if (cartLine.merchandise.product.productType !== 'Accessories') {
 return null; // Do not render the UI if the product type is not 'Accessories'
 }
```

The next big piece of the puzzle is to be able to write our attribute changes when the checkbox and textfield are interacted with. That's managed by a `useApplyCartLinesChange` function [available to the UI Extension](https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/react-hooks/attributes/useapplyattributechange). Big callout here; there is also an option to set the attribute directly on the *cart* and not the *cart lines* -- but it'll entirely break our expected outcome, because any Cart Transform function would then modify the prices of every single cart line.

This also means that the resulting order in the admin outputs the attributes directly under each line item nicely, for any downstream systems or customer service agents to use when processing or fulfilling the items.

```javascript
const updateCartLineAttributes = async (isChecked, customText) => {
 // Create a CartLineUpdateChange object
 const change = {
 type: "updateCartLine",
 id: cartLine.id,
 attributes: [
 {
 key: "added_customisation",
 value: isChecked ? "true" : "false",
 },
 {
 key: "custom_text",
 value: customText,
 },
 ],
 };

 // Call the API to modify checkout
 const result = await applyCartLinesChange(change);
 console.log("applyCartLinesChange result", result);
 };
```

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FIEMcoMk764PAyYNrLYDAf87TxR42%2FY9cDomNn0JqUkpmWkQdQ%2Fe2c66d0f-4432-417e-ae0c-d71564b61153.png?alt=media&token=06d3acbe-4083-4128-aa84-15674c87f876","id":"e2c66d0f-4432-417e-ae0c-d71564b61153","width":1131,"height":621,"filename":"Screenshot 2024-09-12 at 17.00.29.png","type":"image/png","caption":"Line Item Attributes are output directly to the order object.","border":false}]}
```

As I was building this out, I also wanted a few quality of life processes built in that would account for edge cases. While the base version was okay, taking the extra few hours to make it *good* was worthwhile. Some scenarios the code is accounting for:

* **IF** the customer has input a value in the textfield, but they uncheck the checkbox - the textfield is wiped and the line item attribute it's setting is erased.

* **IF** the customer adds more than 25 characters, it serves an error but it *also* refuses to add it's line item attribute.

* **IF** you've set your custom text and it's created a line item attribute, but then you erase your text, it also clears the set line item attribute.

One improvement I think would be neat is implementing the textfield rendering within a [Disclosure](https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/components/interactive/disclosure) controlled by the checkbox - but that's for another day.

**\[Note: I'll share the full code for the checkout.jsx at the bottom of this post\]**

Okay, now that we've got our Checkout UI Extension setting an attribute, we need to use it within a Function to modify our line item prices conditionally.

I've made this really easy to debug, because I'm outputting the `added_customisation` line item attribute and it's `true` or `false` value directly to the Checkout. You could choose to make it a hidden property simply by appending it with an underscore so it's `_added_customisation`.

For our function, we want to fetch that attribute with our input query:

```graphql
query RunInput {
 cart {
 lines {
 id
 quantity
 cost {
 amountPerQuantity {
 amount
 currencyCode
 }
 }
 attribute(key: "added_customisation") {
 value
 }
 }
 }
}
```

Then essentially, we want to use that attribute value to decide wether or not we modify any line items that have the value set as `true`, which again is directly controlled by our checkbox we've built within our Extension UI.

```
const isCustomised = cartLine.attribute?.value === 'true';
```

Pretty simple! If the cart line's attribute(s) have the right value, then we return the Cart Transform operation to that line. I've hardcoded my code to apply a %10 markup (base price x 1.10) when a customisation is applied, but you could also take a merchant-configured metafield value supplied by an embedded UI as an input and use that to determine what value of markup to output in the Function. That's a whole other ballgame - review [this Discounts UI tutorial](https://shopify.dev/docs/apps/build/discounts/build-ui-with-remix?extension=javascript) for an example of how that might work.

***Note:** Hosting an app with a front end UI to take a merchant-defined metafield value turns this from an extension-only app (hosted & scaled by Shopify) to a full custom app deployment (your own hosting & scaling considerations for the frontend).*

Some caveats do exist here that I (regrettably) have to mention in this otherwise perfect (thanks very much) approach:

* I am, quite obviously, not accounting for **multiples**. If I had 3x beanies in my cart, I'm getting 3x customised beanies, baby -- if I wanted them or not. If you need to split similar line items between customised and non-customised, consider a different variant for each, and modify the cart accordingly (with `useApplyCartLinesChange` and it's [remove or update actions](https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/react-hooks/cart/useapplycartlineschange)). Another option is to limit any customisable items to a quantity of one.

* Setting attributes may not be available in certain scenarios, such as draft orders or accelerated wallet checkouts. Make sure you're accounting for those journeys.

* This can't be combined with other active Cart Transform functions, otherwise they'll compete on pricing. If you have a custom bundle app or similar solution, make sure that customisation pricing logic is *embedded* into that bundling code, and not running alongside it.

* None of this has any validation behind it, and that'd be a good idea. A Cart & Checkout Validation function could double check that a line item attribute isn't beyond a certain length, or somehow a product got a price it shouldn't have, etc.

Here's the various files and their full codes involved in this solution. Hope it helps, especially as a building block towards other use cases!

✌️

**Function: run.js**

```javascript
// @ts-check

/**
 * @typedef {import("../generated/api").RunInput} RunInput
 * @typedef {import("../generated/api").FunctionRunResult} FunctionRunResult
 * @typedef {import("../generated/api").CartOperation} CartOperation
 */

/**
 * @type {FunctionRunResult}
 */
const NO_CHANGES = {
 operations: [],
};

/**
 * @param {RunInput} input
 * @returns {FunctionRunResult}
 */
export function run(input) {
 const operations = input.cart.lines.reduce(
 /** @param {CartOperation[]} acc */
 (acc, cartLine) => {
 // Check if the cart line attribute 'added_customisation' is set to 'true'
 const isCustomised = cartLine.attribute?.value === 'true';

 if (isCustomised) {
 const updateOperation = buildUpdateOperation(cartLine);
 if (updateOperation) {
 acc.push({ update: updateOperation });
 }
 }
 return acc;
 },
 /** @type {CartOperation[]} */ ([]),
 );

 return operations.length > 0 ? { operations } : NO_CHANGES;
}

/**
 * @param {RunInput['cart']['lines'][number]} cartLine
 * @returns {CartOperation['update'] | null}
 */
function buildUpdateOperation(cartLine) {
 const { id: cartLineId, cost: { amountPerQuantity } } = cartLine;

 if (amountPerQuantity) {
 const originalPrice = Number(amountPerQuantity.amount);
 const markupPrice = originalPrice * 1.10; // Apply 10% markup

 return {
 cartLineId,
 price: {
 adjustment: {
 fixedPricePerUnit: {
 amount: markupPrice.toFixed(2) // Ensure the price is formatted to 2 decimal places
 }
 }
 }
 };
 }

 return null;
}
```

**Checkout UI Extension:** **checkout.jsx**

```javascript
import {
 reactExtension,
 Banner,
 BlockStack,
 View,
 Checkbox,
 Text,
 TextBlock,
 TextField,
 BlockSpacer,
 useApi,
 useApplyCartLinesChange,
 useInstructions,
 useTranslate,
 useCartLineTarget,
} from "@shopify/ui-extensions-react/checkout";
import React, { useState } from 'react';

// 1. Choose an extension target
export default reactExtension("purchase.checkout.cart-line-item.render-after", () => (
 <Extension />
));

function Extension() {
 const translate = useTranslate();
 const { extension } = useApi();
 const instructions = useInstructions();
 const applyCartLinesChange = useApplyCartLinesChange();
 const cartLine = useCartLineTarget();

 // 2. Check instructions for feature availability, see https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions for details
 if (!instructions.attributes.canUpdateAttributes) {
 // For checkouts such as draft order invoices, cart attributes may not be allowed
 // Consider rendering a fallback UI or nothing at all, if the feature is unavailable
 return (
 <Banner title="product-customiser-ui" status="warning">
 {translate("attributeChangesAreNotSupported")}
 </Banner>
 );
 }

 // 3. Check if the cart line is an accessory
 if (cartLine.merchandise.product.productType !== 'Accessories') {
 return null; // Do not render the UI if the product type is not 'Accessories'
 }

 // 4. Manage Checkbox and TextField State
 const [isChecked, setIsChecked] = useState(false);
 const [customText, setCustomText] = useState("");
 const [error, setError] = useState("");

 // 5. Handle Checkbox Change
 const onCheckboxChange = (checked) => {
 setIsChecked(checked);
 const newCustomText = checked ? customText : "";
 setCustomText(newCustomText);
 updateCartLineAttributes(checked, newCustomText);
 };

 // 6. Handle TextField Change
 const onTextFieldChange = (value) => {
 if (value.length > 25) {
 setError("Max 25 characters, please");
 } else {
 setError("");
 setCustomText(value);
 updateCartLineAttributes(isChecked, value);
 }
 };

 // 7. Update Cart Line Attributes
 const updateCartLineAttributes = async (isChecked, customText) => {
 // Create a CartLineUpdateChange object
 const change = {
 type: "updateCartLine",
 id: cartLine.id,
 attributes: [
 {
 key: "added_customisation",
 value: isChecked ? "true" : "false",
 },
 {
 key: "custom_text",
 value: customText,
 },
 ],
 };

 // Call the API to modify checkout
 const result = await applyCartLinesChange(change);
 console.log("applyCartLinesChange result", result);
 };

 // 8. Render a UI
 return (
 <BlockStack border={"dotted"} padding={"tight"}>
 <View border="base" padding="base">
 <Checkbox onChange={onCheckboxChange} checked={isChecked}>
 <Text>Yes, add custom embroidery for small fee.</Text>
 </Checkbox>
 </View>
 {isChecked && (
 <View border="base" padding="base">
 <TextField
 label="Your Custom Text"
 value={customText}
 onChange={onTextFieldChange}
 required={isChecked}
 error={error}
 />
 <BlockSpacer spacing="loose" />
 <TextBlock size="small" emphasis="italic" appearance="subdued" inlineAlignment="end">{customText.length}/25</TextBlock> {/* Display character count */}
 </View>
 )}
 </BlockStack>
 );
}
```

Adjust Prices via Checkout UI Extension

[2025] Guide to Shopify Checkout

Find me everywhere online via @mackiec or through my website mackiec.xyz

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://mackiec.xyz/japan-4x6-project](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

2024