Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 55 ยท App Extensions

Customer Account and POS Extensions

Extend Shopify beyond the storefront: customer account pages, the order status page and point of sale. Learn targets, use cases, constraints and when to pick each.

So far the extensions in this chapter lived in the theme, the admin and checkout. Two more surfaces matter for many merchants. The customer account is where buyers look at orders, track deliveries, start returns and edit their profile. Point of sale (POS) is the Shopify app that store staff use on a phone, tablet or register to sell in person.

Both surfaces are extended with the same idea you already know from Checkout UI Extensions: your code is a small UI extension that Shopify renders at a named target, inside a sandbox, using Shopify's own components. You never get raw access to the page. This lesson explains what each surface offers, how you pick a target, and which constraints to plan around.

What runs here. Customer accounts, the order status page and POS need real Shopify surfaces, so the real configuration and code in this lesson are read-only. The runnable examples are plain JavaScript stand-ins: a target picker and a tiny renderer that show the decision-making and the data flow. Target names, available APIs and plan requirements change; confirm them in the current extension documentation before you build.

Customer account extensions

The customer account experience has pages such as an order list, an order detail (status) page and a profile page. A customer account UI extension can add content to those pages, or add an entire new page of its own.

Typical use cases:

  • Show a loyalty balance or a "Reorder" shortcut on the order list.
  • Add extra order information on the order status page: delivery instructions, an installation guide, a warranty registration button.
  • Add a custom page ("My subscriptions", "My wishlist") reachable from the account navigation.
  • Start a return, exchange or repair request from an order.

Targets follow a readable pattern: customer-account.<page>.<position>.render. A few you will meet (check the current list for exact names):

Target Where it renders
customer-account.order-status.block.render A block on the order status page
customer-account.order-index.block.render A block on the order list page
customer-account.profile.block.render A block on the profile page
customer-account.page.render A full page that you own, with its own navigation link

A block target adds one section among Shopify's own. A page target gives you a whole page. Merchants decide, in the customer account editor, where block extensions sit, just as they place app blocks in the theme editor.

Extension configuration (read-only)

An extension is declared in its own shopify.extension.toml (the same file type as in App Extensions Overview):

TOML
api_version = "2026-07"

[[extensions]]
type = "ui_extension"
name = "Delivery notes"
handle = "delivery-notes"

[[extensions.targeting]]
target = "customer-account.order-status.block.render"
module = "./src/OrderStatusBlock.jsx"

[extensions.capabilities]
network_access = false
api_access = true

api_access allows the extension to call the Customer Account API or the Storefront API through the provided fetch helper. network_access is only for calling your own servers directly, and it needs approval in some cases. Stay on the smallest permission set that works.

Extension code (read-only)

The code is a function that returns UI built from Shopify's components, and it reads data through a global shopify object:

JSX
import '@shopify/ui-extensions/preact';
import { render } from 'preact';

export default function extension() {
  render(<OrderNote />, document.body);
}

function OrderNote() {
  const order = shopify.order.value; // reactive value for the current order
  return (
    <s-banner tone="info">
      Your order {order?.name} ships within 2 business days.
    </s-banner>
  );
}

The exact imports, signals and component set have changed between API versions (older extensions used React hooks from a package such as @shopify/ui-extensions-react). Treat this as the shape of an extension, not as copy-paste code.

The order status page

The order status page is the page a buyer sees right after paying (the thank-you page) and when they follow the tracking link in their confirmation email. It is the highest-attention moment in the whole purchase, which is why apps use it for surveys, upsells to related items, account sign-up prompts and support information.

Customer account order pages and the thank-you page share their data model, so a well-designed extension reads the order, the line items and the shipping address, then decides what to show. Keep it small: buyers came here to see their order, and an extension that pushes the real content down the page is a bad experience and a review risk. See App Store Requirements and Review.

POS UI extensions

POS UI extensions add tiles, screens and actions to the POS app itself. Staff use POS at a counter or on the shop floor, so the rules differ from the web:

  • Touch-first, quick. Interactions are taps on a small screen; every extra step costs real queue time.
  • Context is the cart or the customer. A POS target can often read the current cart, the selected customer or the product being viewed.
  • Connectivity can be poor. A shop's Wi-Fi drops. Design for failure and for slow calls.
  • No arbitrary UI. You build with POS components (lists, buttons, text fields, screens), not with HTML.

Common use cases are a home tile that opens a custom workflow (a daily cash-up helper, a gift-card lookup), an action on a product (check stock at nearby locations), and a block on the post-purchase screen (collect a newsletter sign-up).

Targets are named like pos.<screen>.<position>.render:

Target Purpose
pos.home.tile.render A tile on the POS home screen
pos.home.modal.render The screen that opens when that tile is tapped
pos.product-details.block.render A block on a product's detail screen
pos.purchase.post.block.render A block shown after a sale completes

A tile and its modal are always a pair: the tile is the button, the modal is the workflow.

TOML
api_version = "2026-07"

[[extensions]]
type = "ui_extension"
name = "Gift card lookup"
handle = "gift-card-lookup"

[[extensions.targeting]]
target = "pos.home.tile.render"
module = "./src/Tile.jsx"

[[extensions.targeting]]
target = "pos.home.modal.render"
module = "./src/Modal.jsx"

POS access depends on the merchant: they must have POS set up, and some capabilities (for example scanner or printer access) may be limited by the device. Always handle "this API is not available" instead of assuming a phone with every feature.

Choosing the right surface

Before building, ask which surface matches the moment you want to influence.

flowchart TD
    Q["Where should it appear?"] --> A{"Buyer on the web<br/>after ordering?"}
    A -- "Yes" --> B["Customer account / order status extension"]
    Q --> C{"Staff selling<br/>in a physical shop?"}
    C -- "Yes" --> D["POS UI extension"]
    Q --> E{"Buyer in checkout<br/>before paying?"}
    E -- "Yes" --> F["Checkout UI extension"]
    Q --> G{"Merchant managing<br/>their store?"}
    G -- "Yes" --> H["Admin UI extension / App Home"]

One question decides the surface: who is looking, and at what moment?

The first stand-in encodes that decision as data. It is a catalog of surfaces and targets with a picker that returns the candidates for a need. The data is a simplified teaching table, not Shopify's registry.

Node.js Extension target picker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last case is the useful lesson: not every idea belongs on these surfaces. A merchant-facing tool goes in the admin.

A tiny render stand-in

Whatever the surface, an extension is a function from data to UI. Test that function without a browser by treating the UI as plain data. This stand-in renders the "delivery notes" block from earlier for a few orders and shows why a defensive extension handles missing data.

Node.js Order status block as a pure function

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In the real extension the returned tree is Preact or Polaris markup, and the data comes from shopify.order, but the idea is identical: keep decisions in a pure function and the rendering thin.

Constraints to plan around

  • Sandbox. Extensions run in an isolated environment: no window, no direct DOM, no cookies, no localStorage. You talk to Shopify through the provided APIs.
  • Network. Calls to Shopify go through the provided API access. Calls to your own server need network_access and CORS support, and your server must authenticate the request with a session token the extension can obtain (see Session Tokens for Embedded Apps).
  • Performance. Slow extensions slow the page they sit on. Render fast, load data lazily, show a skeleton.
  • Plan and availability. Some customer account and order status targets, and some POS features, are limited by the merchant's plan, region or device. Plan for the target not being available.
  • Versioning. Each extension declares an api_version. Deploying a new extension version does not change what is live until you release it, as in App Extensions Overview.
  • Privacy. Customer data is protected data. Read only what you need, and see Privacy, GDPR and Mandatory Webhooks.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which surface should you extend to add a "daily cash-up" workflow for store staff?

    Store staff use the POS app. A home tile starts the workflow and its modal holds the screens.
  2. 2. What does a target such as customer-account.order-status.block.render tell Shopify?

    A target names a place in a surface. Here it is a block on the order status page.
  3. 3. Why design extension logic as a pure function from data to UI?

    Extensions run in a sandbox with no DOM of their own. Keeping decisions in a plain function makes them easy to unit test, including cases where the order is missing.
  4. 4. Why should an order status extension stay small?

    Buyers come to see their order. Heavy or intrusive extensions hurt the experience and can fail app review.

Summary

  • Customer account extensions add blocks or whole pages to order list, order status and profile; POS extensions add tiles, screens and blocks to the POS app.
  • Both are sandboxed UI extensions rendered at named targets with Shopify's components; configuration lives in shopify.extension.toml.
  • A POS home tile and its modal come as a pair; POS design is touch-first, fast and tolerant of poor connectivity.
  • Pick the surface by audience and moment: buyer after ordering, staff in a shop, buyer in checkout, merchant in the admin.
  • Keep logic in pure functions, render nothing when data is missing, request the fewest permissions, and check target names and plan limits in the current docs.

Next: App Proxy and Storefront Pages.