Mark POS .observe extension targets as @deprecated by vctrchu · Pull Request #4146 · Shopify/ui-extensions

vctrchu · 2026-03-18T19:55:18Z

What

Adds @deprecated and @private JSDoc annotations to all 4 POS observe extension targets, pointing developers to pos.app.ready.data + window.addEventListener() as the replacement.

Targets deprecated

Observe target	Replacement
`pos.transaction-complete.event.observe`	`window.addEventListener('transactioncomplete', cb)` on `pos.app.ready.data`
`pos.cash-tracking-session-start.event.observe`	`window.addEventListener('cashtrackingsessionstart', cb)` on `pos.app.ready.data`
`pos.cash-tracking-session-complete.event.observe`	`window.addEventListener('cashtrackingsessioncomplete', cb)` on `pos.app.ready.data`
`pos.cart-update.event.observe`	`api.cart.current.subscribe()` on `pos.app.ready.data`

Why

The observe targets are fire-and-forget — they run once per event with no persistent state, no access to APIs, and no way to correlate events. pos.app.ready.data is a persistent background target that runs for the entire session, receives events via the standard window.addEventListener() Web API, and has full access to non-UI APIs (cart, storage, session, locale, connectivity, device, product search).

Notes

Annotations only — no runtime behavior changes
@private excludes these from generated shopify.dev documentation
Existing extensions using these targets continue to work unchanged
cart_update has no event equivalent in PosEventMap — cart state is continuous, not discrete, so the replacement is the subscribable api.cart.current.subscribe() pattern

Related PRs

Types: feat(pos): add TypeScript types for pos.app.ready.data background target #4123
TAG proposal: https://github.com/Shopify/ui-api-design/pull/1418

Resolves: https://github.com/shop/issues-retail/issues/26066
Epic: https://github.com/shop/issues-retail/issues/26019

Test plan

yarn build passes
CI passes (annotations only, no runtime changes)

github-actions · 2026-03-18T19:55:26Z

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

We are actively migrating UI extension reference docs to MDX in the areas/platforms/shopify-dev zone of the monorepo. This impacts docs for the following surfaces:

During this migration, please be aware of the following:

.doc.ts files are being deprecated. Changes to .doc.ts files in this repo will not be reflected in the new MDX-based docs. If you need to update docs for a reference that has already been migrated, make your changes directly in the areas/platforms/shopify-dev zone of the monorepo instead.

Doc comments in .ts source files (the comment blocks above types and functions) are also affected. Generating docs from these comments currently requires a newer version of the @shopify/generate-docs library that isn't yet available. Updates to doc comments may not produce the expected output until the migration is complete.

Examples that previously lived in this repo are being moved to the areas/platforms/shopify-dev zone of the monorepo and should be authored there going forward.

What should I do?

If your PR includes changes to .doc.ts files, doc comments, or examples, please reach out to us in #devtools-proj-templated-refs so we can help ensure your updates are captured correctly.
If your PR is limited to source code changes (non-docs), you can ignore this notice.

Thanks for your patience while we complete the migration! 🙏

@deprecated

Add @deprecated and @Private JSDoc annotations to all 4 POS observe extension targets: - pos.transaction-complete.event.observe - pos.cash-tracking-session-start.event.observe - pos.cash-tracking-session-complete.event.observe - pos.cart-update.event.observe Each annotation includes the deprecation version (2026-04), migration path to pos.app.ready.data + shopify.addEventListener(), and a link to the new target's documentation. pos.cart-update.event.observe also references shopify.cart.current.subscribe() as an alternative for render targets. Resolves: shop/issues-retail#26066 Epic: shop/issues-retail#26019 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…_update event reference

mcvinci

Hey @vctrchu! Responded to your question, and also added a couple of other comments! ❤️

mcvinci · 2026-03-31T23:05:10Z

+  /**
+   * Fires when a cash tracking session starts.
+   *
+   * @deprecated Deprecated as of `2026-04`. Use `pos.app.ready.data` target with


Shouldn't these all be deprecated as of 2025-10?

mcvinci · 2026-03-31T23:05:23Z

+   *
+   * @deprecated Deprecated as of `2026-04`. Use `pos.app.ready.data` target with
+   * `window.addEventListener('cash_tracking_session_start', callback)` instead.
+   * See https://shopify.dev/docs/api/pos-ui-extensions/unstable/targets/pos-app-ready-data


These URLs don't exist.

Fixed to use latest

…derscores)

mcvinci

Hey @vctrchu! Took another quick look, and added some further suggestions! ❤️ Thanks again for these docs!

mcvinci · 2026-04-02T20:35:42Z

+   *
+   * @deprecated Deprecated as of `2025-10`. Use `pos.app.ready.data` target with
+   * `window.addEventListener('transactioncomplete', callback)` instead.
+   * See https://shopify.dev/docs/api/pos-ui-extensions/latest/targets/pos-app-ready-data


Quick question: Is this a URL to a page that currently exists?

Let's embed the URL as part of the running text. So something like "Use the [pos.app.ready.app target](link). Also, let's use the version variable in URLs like this:

/docs/api/pos-ui-extensions/{API_VERSION}/targets/pos-app-ready-data

Good call! The pos.app.ready.data target page doesn't exist yet — it'll go live with the 2026-04 API
I've updated all 4 deprecation blocks to:

Add "the" before pos.app.ready.data ✅

Inline the URL in the text as [pos.app.ready.data target](link) instead of a separate "See" line ✅

Use {API_VERSION} variable in URLs ✅

Awesome, thanks, @vctrchu!

mcvinci

🚀

vctrchu self-assigned this Mar 18, 2026

js-goupil approved these changes Mar 18, 2026

View reviewed changes

vctrchu mentioned this pull request Mar 30, 2026

feat(pos): add TypeScript types for pos.app.ready.data background target #4123

Draft

vctrchu force-pushed the deprecate-observe-targets branch from df3502f to 83aff98 Compare March 31, 2026 01:12

vctrchu and others added 2 commits March 30, 2026 18:14

fix: use window.addEventListener in deprecation messages, remove cart…

7386990

…_update event reference

vctrchu force-pushed the deprecate-observe-targets branch from 83aff98 to 7386990 Compare March 31, 2026 01:14

vctrchu requested review from a team and NathanJolly March 31, 2026 01:14

vctrchu marked this pull request as ready for review March 31, 2026 02:10

fatbattk reviewed Mar 31, 2026

View reviewed changes

Comment thread packages/ui-extensions/src/surfaces/point-of-sale/extension-targets.ts

mcvinci reviewed Mar 31, 2026

View reviewed changes

vctrchu added 3 commits April 1, 2026 13:22

Address review: deprecation version 2025-10, fix doc URLs to latest

fbcbc31

Fix event names to match ui-api-design (lowercase concatenated, no un…

99ef265

…derscores)

Simplify cart deprecation wording: point to pos.app.ready.data target

4334abc

vctrchu requested review from fatbattk and mcvinci April 1, 2026 20:35

fatbattk approved these changes Apr 1, 2026

View reviewed changes

mcvinci reviewed Apr 2, 2026

View reviewed changes

Address review: inline URLs with {API_VERSION}, add 'the' article

8e9192b

mcvinci approved these changes Apr 2, 2026

View reviewed changes

vctrchu marked this pull request as draft April 9, 2026 19:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Mark POS .observe extension targets as @deprecated#4146

Mark POS .observe extension targets as @deprecated#4146
vctrchu wants to merge 6 commits into2026-04-rcfrom
deprecate-observe-targets

vctrchu commented Mar 18, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 18, 2026

Uh oh!

Uh oh!

mcvinci left a comment

Uh oh!

Uh oh!

mcvinci Mar 31, 2026

Uh oh!

mcvinci Mar 31, 2026

Uh oh!

vctrchu Apr 1, 2026

Uh oh!

mcvinci left a comment

Uh oh!

Uh oh!

mcvinci Apr 2, 2026

Uh oh!

vctrchu Apr 2, 2026 •

edited

Loading

Uh oh!

mcvinci Apr 2, 2026

Uh oh!

Uh oh!

Uh oh!

mcvinci left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

vctrchu commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Targets deprecated

Why

Notes

Related PRs

Test plan

Uh oh!

github-actions bot commented Mar 18, 2026

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

What should I do?

Uh oh!

Uh oh!

mcvinci left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mcvinci Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

mcvinci Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

vctrchu Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

mcvinci left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mcvinci Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

vctrchu Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcvinci Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mcvinci left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vctrchu commented Mar 18, 2026 •

edited

Loading

vctrchu Apr 2, 2026 •

edited

Loading