preetamnath/post-purchase-ui-extension

Post-Purchase UI Extension

Component catalog, lifecycle contract, and sandbox rules for @shopify/post-purchase-ui-extensions-react (post-purchase upsell surface, npm 0.13.5, package in maintenance — no newer version exists; the modern <s-*> checkout-extensions SDK has no post-purchase target as of writing).

⚠️ MANDATORY: Validate with tsc (do not skip)

Run after writing or editing any post-purchase JSX:

cd extensions/<your-extension>
npx tsc --noEmit

TypeScript resolves types automatically via the bundled .d.ts at node_modules/@shopify/post-purchase-ui-extensions-react/build/ts/index.d.ts. If types fail twice on the same artifact, stop and surface the error to the user.

NEVER call validate_component_codeblocks, validate_graphql_codeblocks, or search_docs_chunks for this SDK. The Shopify Dev MCP doesn't index @shopify/post-purchase-ui-extensions-react. The validator's polaris-checkout-extensions enum value covers the modern @shopify/ui-extensions web-component SDK only and rejects every post-purchase component (BlockStack, Button, …) as "not a Polaris web component."

⚠️ Skip if a different surface

• Admin App Home <s-*> markup → use shopify-polaris-app-home instead.
• Modern checkout extensions (@shopify/ui-extensions-react, <s-*> web components) → use shopify-polaris-checkout-extensions instead.
• Customer account extensions → use shopify-polaris-customer-account-extensions instead.

Doc lookup (WebFetch only)

The MCP doesn't index this SDK — use WebFetch:

• Component props: https://shopify.dev/docs/api/checkout-extensions/post-purchase/components/<name> (lowercase — PascalCase URLs return 404, e.g. /components/blockstack works, /components/BlockStack does not)
• Lifecycle, useExtensionInput, Changeset, InputData, ChangesetErrorCode: https://shopify.dev/docs/api/checkout-extensions/post-purchase/api
• End-to-end tutorials: https://shopify.dev/docs/apps/build/checkout/product-offers/build-a-post-purchase-offer and https://shopify.dev/docs/apps/build/checkout/product-offers/create-a-post-purchase-subscription
• UX guidance (only when working on copy, layout, or offer framing — not for API/prop questions): https://shopify.dev/docs/apps/build/checkout/product-offers/ux-for-post-purchase-product-offers and https://shopify.dev/docs/apps/build/checkout/product-offers/ux-for-post-purchase-subscriptions

If a component, prop, lifecycle field, or error code is missing from the Component Catalog or Lifecycle Contract below, WebFetch the canonical reference.

Rules

• Two extension points, two phases. extend("Checkout::PostPurchase::ShouldRender", …) is a data-prefetch hook; render("Checkout::PostPurchase::Render", App) is the React mount. Render runs only if ShouldRender returned { render: true }. See Lifecycle Contract.
• storage.update(data) in ShouldRender; storage.initialData in Render. Storage is the only hand-off between the two phases — they run in separate JS contexts.
• applyChangeset takes a signed JWT string, not a Changeset object. Sign the changeset on your backend with the app's API secret, return the token to the extension, then call await applyChangeset(token). Never sign client-side.
• Always call done(), including on error paths. Documented behavior: done() "indicates that the extension has finished running" and "redirects customers to the Order status page." Build-guide code samples call it in both accept and decline branches. Operational rule (not stated in shopify.dev): if an accept handler throws or rejects before done() runs, the buyer is stuck on a blank screen — wrap accept handlers in try/finally to guarantee the call.
• Treat ShouldRender as potentially called more than once per checkout. The shopify.dev pages do not document call frequency. Operational observation in production: it can fire on payment-page load and again after the buyer clicks Pay. Make the handler idempotent (backend dedupe of identical fetches keyed by referenceId).
• Sandbox: no DOM, no CSS, no window, no external scripts. All visual customization happens through component props. There is no <style>, no className, no inline style={…}. Spacing comes from prop tokens — but the scale differs per component (see Spacing scales).
• .jsx / .js extension required in every import. The Shopify CLI bundler does not auto-resolve. import { X } from "./foo" fails; import { X } from "./foo.jsx" works.
• Only import what the SDK re-exports from "react". The runtime bundles its own React — importing additional React entry points causes duplicate-React errors. useState, useEffect, etc. work because they pass through.
• Validate with tsc, not the MCP. See MANDATORY block above.

Common Patterns

Generic SDK patterns. Repo-specific architecture (layouts/templates/components, normalize functions, config/token systems) lives in the consuming repo's architecture.md, not here.

Boilerplate entry point

The two-phase contract — every post-purchase extension starts with this skeleton.

import { extend, render } from "@shopify/post-purchase-ui-extensions-react";

extend("Checkout::PostPurchase::ShouldRender", async ({ inputData, storage }) => {
  const data = await fetchOffer(inputData);    // your backend
  if (!data) return { render: false };
  await storage.update(data);
  return { render: true };
});

render("Checkout::PostPurchase::Render", App);

function App({ storage, applyChangeset, done }) {
  const offer = storage.initialData;
  return <BlockStack spacing="loose">{/* … */}</BlockStack>;
}

Loading state on accept Button

Button has a built-in loading prop — flip it on press to disable double-clicks during the sign-changeset round trip. No reset needed; done() navigates away.

const [loading, setLoading] = useState(false);
<Button
  loading={loading}
  loadingLabel="Processing"
  onPress={async () => {
    setLoading(true);
    const token = await signChangeset(variantId);
    await applyChangeset(token);
    done();
  }}
>
  Add to order
</Button>

Image with locked aspect ratio

Use aspectRatio + fit="cover" to prevent layout shift and align cards in a Tiles grid when source images have varying intrinsic ratios.

<Image source={url} description={alt} aspectRatio={1} fit="cover" />

Heading semantics via HeadingGroup

Heading levels are derived from HeadingGroup nesting depth — never set level manually unless you need to override visuals.

<HeadingGroup>
  <Heading>Section title</Heading>
  <HeadingGroup>
    <Heading>Subsection title</Heading>
  </HeadingGroup>
</HeadingGroup>

---

Lifecycle Contract

Extension points

| Point | String | Purpose | |---|---|---| | ShouldRender | Checkout::PostPurchase::ShouldRender | Data prefetch. Decide whether to render. | | Render | Checkout::PostPurchase::Render | Mount the React tree. |

ShouldRender API

(api: PostPurchaseShouldRenderApi) => { render: boolean } | Promise<{ render: boolean }>

api exposes inputData: InputData, storage, plus version / locale / extensionPoint from the standard surface.

• storage.update(data: any): Promise<void> — persist data for the Render phase. Returns a Promise — await it before returning.
• Return { render: true } to mount, { render: false } to skip silently. May return synchronously or as a Promise.

Render API

render("Checkout::PostPurchase::Render", (api: PostPurchaseRenderApi) => ReactElement)

| Field | Type | Use | |---|---|---| | inputData | InputData | Same shape as ShouldRender. | | storage.initialData | unknown | Data written by ShouldRender via storage.update. Read-only. | | calculateChangeset | (changeset: Readonly<Changeset> \| string) => Promise<CalculateChangesetResult> | Preview cost impact without applying. Pass either a raw Changeset object or the signed JWT string. | | applyChangeset | (changeset: string, options?: ApplyChangesetOptions) => Promise<ApplyChangesetResult> | Apply the order edit and charge the buyer. The changeset parameter is a JWT string signed by your backend with the app secret — despite the name, this overload does not accept a raw object. | | done | () => Promise<void> | Navigate to thank-you page. Always call this, success or error. | | version / locale / extensionPoint | from StandardApi | Available alongside inputData. |

InputData

| Field | Type | |---|---| | extensionPoint | string | | initialPurchase | Purchase (referenceId, customerId?, destinationCountryCode?, totalPriceSet, lineItems[]) | | locale | string | | shop | Shop (id: number, domain, metafields) | | token | string (JWT — pass to your backend for verification) | | version | string (current value: 'unstable') |

LineItem: product, quantity, totalPriceSet, sellingPlanId?. Product: id, title, variant, metafields. Metafield.value is string | number; valueType is 'integer' | 'string' | 'json_string'.

Changeset shape

Changeset { changes: Changes }
Changes = (AddVariantChange | AddShippingLineChange | SetMetafieldChange | AddSubscriptionChange)[]

ApplyChangesetOptions

| Option | Type | Use | |---|---|---| | buyerConsentToSubscriptions? | boolean | Set when changes include add_subscription; pair with BuyerConsent component. Optional in the type, but required by the server for subscription changes. |

ChangesetErrorCode

payment_required · insufficient_inventory · changeset_already_applied · unsupported_payment_method · invalid_request · server_error · buyer_consent_required · subscription_vaulting_error · subscription_contract_creation_error · subscription_no_shipping_address_error · subscription_limit_error · order_released_error

---

Component Catalog

29 components total, served by 28 doc URLs under /components/<name> (lowercase). FormLayoutGroup shares the formlayout page rather than having its own URL — when looking it up, fetch /components/formlayout.

All importable from @shopify/post-purchase-ui-extensions-react.

Spacing scales

There is no single "spacing scale" — three different scales coexist. Match the literal exactly to the consumer's .d.ts:

| Scale | Allowed values | Used by | |---|---|---| | Stack scale | 'xtight' \| 'tight' \| 'loose' \| 'xloose' | BlockStack.spacing, InlineStack.spacing, Bookend.spacing | | Stack scale + none | 'none' \| 'xtight' \| 'tight' \| 'loose' \| 'xloose' | Tiles.spacing | | Compact scale | 'none' \| 'tight' \| 'loose' | TextContainer.spacing, CalloutBanner.spacing | | View padding scale | 'extraTight' \| 'tight' \| 'base' \| 'loose' \| 'extraLoose' | View.inlinePadding, View.blockPadding |

xtight/xloose and extraTight/extraLoose are NOT interchangeable — each is rejected by the component that doesn't list it.

Layout & Structure

| Component | Purpose | Key Props / Gotchas | |---|---|---| | BlockStack | Vertical stack | spacing: stack scale (no none). alignment: 'leading' \| 'center' \| 'trailing'. | | InlineStack | Horizontal row | spacing: stack scale. alignment: 'leading' \| 'center' \| 'trailing' \| 'baseline'. | | Bookend | Pin first/last child to intrinsic size, fill middle | leading?: boolean, trailing?: boolean. spacing: stack scale. alignment: 'leading' \| 'center' \| 'trailing' \| 'baseline'. | | Tiles | Equal-size grid, wraps and stacks responsively | maxPerLine?: number. breakAt?: number (px width below which tiles stack). spacing: stack scale + 'none'. alignment: 'leading' \| 'center' \| 'trailing' \| 'baseline'. Direct children stretch — wrap a child in View to keep its intrinsic size. | | Layout | Multi-section page scaffold with media-queried sizes | maxInlineSize?: number (≤1 = %, >1 = px). sizes?: Size[] where Size = 'auto' \| 'fill' \| number. media?: Media[] where Media = { viewportSize: 'small' \| 'medium' \| 'large'; maxInlineSize?: number; sizes?: Size[] }. inlineAlignment?: 'leading' \| 'trailing'. blockAlignment?: 'center' \| 'trailing'. No spacing prop exists on LayoutProps despite appearing in some doc code samples — using it is a TS error. | | View | Generic container that does NOT stretch | inlinePadding / blockPadding: View padding scale ('extraTight' \| 'tight' \| 'base' \| 'loose' \| 'extraLoose'). Note camelCase — NOT xtight/xloose. Use to opt out of Tiles/Layout stretching. | | Separator | Visual divider | direction: 'horizontal' (default) / 'vertical'. width: 'thin' \| 'medium' \| 'thick' \| 'xthick'. |

Typography

| Component | Purpose | Key Props / Gotchas | |---|---|---| | Heading | Section title | level?: 1 \| 2 \| 3 — visual override only; semantic level comes from HeadingGroup nesting. role?: 'presentation' strips semantics, keeps styling. | | HeadingGroup | Increments heading level for nested children | No props. Wrap children that contain their own Heading to bump them down a level semantically. | | Text | Inline styled text | size?: 'small' \| 'medium' \| 'large' \| 'xlarge'. emphasized?: boolean, subdued?: boolean. id?: string. appearance?: 'critical' \| 'warning' \| 'success'. role: string 'address' or 'deletion' (use deletion for strikethrough on original prices), or an object: { type: 'abbreviation'; for?: string }, { type: 'directional-override'; direction: 'ltr' \| 'rtl' } (direction is required), { type: 'datetime'; machineReadable?: string }. Inline only — wrap in TextBlock or a stack to break to a new line. | | TextBlock | Block-level paragraph | size?: 'small' \| 'medium' \| 'large' \| 'xlarge'. emphasized?: boolean, subdued?: boolean. id?: string. appearance?: 'critical' \| 'warning' \| 'success'. No role prop. | | TextContainer | Vertical spacing wrapper for text elements | spacing?: 'none' \| 'tight' \| 'loose' (compact scale — xtight/xloose are NOT accepted here). alignment?: 'leading' \| 'center' \| 'trailing'. |

Actions

| Component | Purpose | Key Props / Gotchas | |---|---|---| | Button | Primary action | onPress?(): void (optional in the type — provide if not using submit or to). submit?: boolean (form submit). to?: string (renders as Link). subdued?: boolean (secondary look), plain?: boolean (link-styled). loading?: boolean + loadingLabel?: string. disabled?: boolean. No variant/tone props — emphasis is via subdued/plain. | | ButtonGroup | Inline-stacked buttons with auto-spacing | No props. Wraps two or more Buttons. | | Link | Navigation | to?: string and/or onPress?(): void — provide at least one. external?: boolean opens in new tab. id?: string (target for accessibility-label associations). Not a button — use Button for actions. |

Forms

| Component | Purpose | Key Props / Gotchas | |---|---|---| | Form | Form wrapper with implicit-submit-on-Enter | onSubmit(): void required. disabled?: boolean. implicitSubmit?: boolean \| string (string = a11y label for screen-reader-only submit button). No <form> HTTP submission — handle in onSubmit. | | FormLayout | Vertical-stacked field layout | No props. Children stack on the block axis. | | FormLayoutGroup | Inline-grouped fields within a FormLayout | No props. Fields appear side-by-side with equal spacing. Lives in the same .d.ts file as FormLayout. | | TextField | Single-line input | label: string (required, doubles as placeholder when empty). value?: string, onChange?(value: string): void (fires on commit/blur). onInput?(value: string): void (fires every keystroke — drive controlled state from onInput, not onChange). type?: 'text' \| 'email' \| 'number' \| 'telephone'. name?: string (form key). id?: string. required?: boolean (semantic only; does not auto-error). error?: string. multiline?: boolean. autocomplete?: Autocomplete \| boolean. tooltip?: { label: string; content: string }. onFocus?(): void, onBlur?(): void. | | Select | Dropdown | label: string (required). options: { value: string; label: string; disabled?: boolean }[]. value?: string, onChange?(value: string): void. placeholder?: string. id?: string, name?: string. required?: boolean. disabled?: boolean (on the Select itself, not just options). error?: string. autocomplete?: Autocomplete \| boolean. | | Checkbox | Boolean toggle | checked?: boolean (preferred) or value?: boolean — checked takes precedence when both are set. onChange?(value: boolean): void. disabled?: boolean, error?: string. id?: string, name?: string, accessibilityLabel?: string. | | Radio | Single radio button | name: string (required — same name groups options). checked?: boolean / value?: boolean. onChange?(value: boolean): void. disabled?: boolean. id?: string, accessibilityLabel?: string. | | BuyerConsent | Subscription consent checkbox | policy: 'subscriptions'. checked: boolean (required), onChange(value: boolean): void (required — unlike other form components). error?: string. Required when applying an add_subscription change with applyChangeset(token, { buyerConsentToSubscriptions: true }). |

Feedback & Status

| Component | Purpose | Key Props / Gotchas | |---|---|---| | Banner | Status / system message | title?: string. status?: 'info' \| 'success' \| 'warning' \| 'critical' (default 'info'). collapsible?: boolean, iconHidden?: boolean. For status reporting — not for promotional copy. | | CalloutBanner | Promotional offer header | title?: string. background?: 'secondary' \| 'transparent' (default 'secondary'). border?: 'none' \| 'block' (default 'block'). alignment?: 'leading' \| 'center' \| 'trailing' (default 'center'). spacing?: 'none' \| 'tight' \| 'loose' (compact scale — xtight/xloose are NOT accepted; default 'tight'). For limited-time-offer framing — distinct from Banner. | | Spinner | Loading indicator | size?: 'small' \| 'large'. color?: 'inherit'. Children = a11y fallback for reduced-motion users. |

Media

| Component | Purpose | Key Props / Gotchas | |---|---|---| | Image | Responsive image | source: string (required). description?: string (alt; default ''). sources?: { source: string; viewportSize?: 'small' \| 'medium' \| 'large'; resolution?: 1 \| 1.3 \| 1.5 \| 2 \| 2.6 \| 3 \| 3.5 \| 4 }[] for responsive variants — resolution is a constrained numeric literal union, not any number. aspectRatio?: number — sets height from width to prevent layout shift. fit?: 'cover' \| 'contain' (pair with aspectRatio to avoid stretch). loading?: 'eager' \| 'lazy'. bordered?: boolean, decorative?: boolean. |

Accessibility

| Component | Purpose | Key Props / Gotchas | |---|---|---| | HiddenForAccessibility | Hide children from a11y tree but show visually | No props. Use for purely decorative or duplicated content. | | VisuallyHidden | Hide visually but keep available to screen readers | No props. Use for screen-reader-only labels. |