Add JSDoc for API properties (2025-10)

[rennyG]

Summary

Adds JSDoc to checkout and customer account API surfaces for properties whose documentation was moved out of ## Limitations sections in shopify-dev. Pairs with the .mdx cleanup in shopify/world#663262 and the multi-agent plan in shopify/world#660052.

References shopify/issues-learn#1612.

Properties touched (Agent 1 scope, A.* and B.*)

Checkout API (packages/ui-extensions/src/surfaces/checkout/api/)

• A.2 Attribute.value (shared.ts)
• A.4 InterceptorRequestAllow.perform and InterceptorRequestBlock.perform (standard.ts)
• A.6 CartLineChangeResultError.message, CheckoutApi.applyCartLinesChange (checkout.ts)
• A.7 StandardApi.checkoutToken (standard.ts)
• A.8 CartCost.totalShippingAmount, CartCost.totalTaxAmount (standard.ts)
• A.9 TrackingConsentMetafieldChange.value, AllowedProcessing.{analytics,marketing,preferences,saleOfData} (standard.ts)
• A.10 StandardApi.deliveryGroups (standard.ts); target and isTargetSelected on CartLineItemApi, ShippingOptionItemApi, PickupLocationItemApi
• A.12 GiftCardChangeResultError.message, CheckoutApi.applyGiftCardChange (checkout.ts)
• A.13 useLocalizedField (preact/localized-fields.ts)
• A.14 NoteChangeResultError.message (checkout.ts)
• A.15 OrderConfirmation.number (order-confirmation.ts)
• A.17 Analytics.publish (standard.ts)
• A.18 Extension.version (standard.ts)
• A.19 Localization.country (standard.ts)
• A.20 MetafieldChangeResultError.message (checkout.ts)
• A.21 SessionToken interface description (standard.ts) — there's no typed sub claim, so the JSDoc lives on the interface itself
• A.24 Storage.read (standard.ts)

Customer account API (packages/ui-extensions/src/surfaces/customer-account/api/)

• B.2 OrderStatusApi.checkoutSettings (order-status.ts)
• B.4 CustomerPrivacy.region (shared.ts)
• B.5 OrderStatusApi.shippingAddress, OrderStatusApi.billingAddress (order-status.ts)
• B.6 Attribute.value (shared.ts)
• B.7 OrderStatusApi.buyerIdentity (order-status.ts)
• B.8 OrderStatusApi.discountAllocations (order-status.ts)
• B.9 AppliedGiftCard.balance (order-status.ts)
• B.10 Metafield.value (order-status.ts)
• B.11 OrderStatusLocalization interface description (order-status.ts)

Follow-up commit (covers content trimmed from .mdx in review feedback on shopify/world#663262):

• OrderStatusApi.requireLogin (order-status.ts) — dismissal-handling guidance
• OrderStatusApi.authenticationState (order-status.ts) — read-only framing

Notes / deviations from the plan

• A.3 buyer-identity (checkout): Reviewer trimmed the level-2 access note from the .mdx intro because it duplicated the <Requires> callout. Existing JSDoc on BuyerIdentity.email and BuyerIdentity.phone in standard.ts already includes "Requires level 2 access to protected customer data" plus the undefined behavior, so no JSDoc edit is needed here.
• A.16 payment options superseded upstream: The availablePaymentOptions and selectedPaymentOptions JSDoc edits in this PR were superseded by upstream commit 2e27e8ea7 Add payment option limitations to availablePaymentOptions and selectedPaymentOptions (Stephanie). Same content, reviewer-improved phrasing. The merge resolution in this PR takes the upstream wording, so A.16 is no longer load-bearing here.
• A.6, A.12, A.14, A.20 error message: The plan's text references "the error code" but these error result types only carry type: 'error' and message: string — no error code field. Adapted the new sentence to "Render your own localized error text rather than displaying this message to the buyer."
• A.21 SessionToken sub claim: There's no typed sub field in the source — the token is a JWT string. Added the guidance to the SessionToken interface description.
• B.14 storefront global fetch(): The fetch() approach uses the standard JS fetch with shopify:storefront/... URLs and has no typed function in the customer account API source. Skipped JSDoc for this version. The .mdx cleanup already covers the guidance.
• Style: Removed em dashes from the plan text (replaced with periods, semicolons, or commas) per the agreed style rules. Kept "only" next to what it modifies.

Test plan

• CI passes on this PR
• Sibling PRs land for 2026-01, 2026-04, 2026-07-rc with byte-identical JSDoc

🤖 Generated with Claude Code

[github-actions]

🚨🚨🚨 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:

• Admin UI extensions
• App Home
• Checkout UI extensions
• Customer account UI extensions
• POS UI extensions

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! 🙏

[github-actions]

We detected some changes in packages/*/package.json or packages/*/src, and there are no updates in the .changeset directory. If the changes are user-facing and should cause a version bump, run yarn changeset to track your changes and include them in the next release CHANGELOG. If you are making simple updates to repo configuration, examples, or documentation, you do not need to add a changeset.