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).

⚠️ Check every prop against the types

Before you write a component prop, find it in the bundled .d.ts at node_modules/@shopify/post-purchase-ui-extensions-react/build/ts/index.d.ts. Memory invents plausible fake props (spacing="base", Button tone).

NEVER run the shopify skill's search_docs.mjs or validate.mjs for this SDK. Its docs don't cover @shopify/post-purchase-ui-extensions-react. Its polaris-checkout-extensions validator accepts only Polaris web components, so it rejects every post-purchase component (BlockStack, Button, …).

⚠️ Skip if a different surface

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

Doc lookup (WebFetch only)

• 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.
• With Shop Pay, storage.initialData is EMPTY in Render. ShouldRender runs on shop.app and Render on the merchant's domain, and Storage does not cross domains (Shopify-documented under product-offers → Limitations, no workaround). Render must refetch when Storage is empty — Oak does it in index.jsx App via loadOffers(inputData, "render", …); Render's inputData carries the same token + initialPurchase. Bound the refetch with a timeout: Shopify's UX guidance says Render network calls should finish within 2s.
• 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.

Common Patterns

These patterns are SDK-generic; the consuming repository's local instructions and code own repository-specific patterns.

Boilerplate entry point

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

import { extend, render, BlockStack } 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;   // empty under Shop Pay — refetch (see Rules)
  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);
    try {
      const token = await signChangeset(variantId);
      await applyChangeset(token);
    } finally {
      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

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. await it before returning.
• Return { render: true } to mount, { render: false } to skip silently.

Render API

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

InputData

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

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, 28 doc URLs under /components/<name> (lowercase): FormLayoutGroup has no page of its own — fetch /components/formlayout.

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

Spacing scales

Spacing literals differ per component — use exactly the values its .d.ts lists:

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

Layout & Structure

Typography

Actions

Forms

Feedback & Status

Media

Accessibility