Skip to main content
Upgrade to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use Polaris web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the upgrade guide to upgrade your extension and avoid being blocked from updating your extension after October 1st 2026.

Payments and returns

Payments and returns extensions render inside the payment status and return status cards on the Order status page. These cards appear alongside Shopify's native payment and return UI so customers see your extension content in direct context with their order's financial and return details.

Anchor to Use casesUse cases

  • Payment reminders: Display notices about outstanding balances, payment terms, or upcoming due dates for orders with pending payments.
  • Cost breakdowns: Show supplementary payment information such as installment details, loyalty point usage, or custom surcharges.
  • Return status updates: Provide customers with additional context about their return, such as estimated refund timelines or return shipping instructions.
  • Return processing details: Display app-specific return information, such as restocking status, exchange options, or return policy reminders.
  • Order-specific messaging: Surface contextual messages related to payment or return activity on an order.
Order status page payments and returns section showing available extension target locations with highlighted slots near payment and return details.

Anchor to Payments and returns targetsPayments and returns targets

Payments and returns targets render inside the payment status and return status cards on the Order status page. They're useful for adding contextual information about payments and returns tied to an order.

Anchor to Payment details (render after) ,[object Object]Payment details (render after) target

customer-account.order-status.payment-details.render-after

Renders after the payment details in the payment status card on the Order status page.

Use this target to display payment reminders, cost summaries, or supplementary payment information for an order. This target gives you access to the Order API and the Cart Lines API.

Support
Components (63)
APIs (28)

Supported components

Available APIs

Examples
import {
reactExtension,
Banner,
useOrder,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.order-status.payment-details.render-after',
() => <Extension />,
);

function Extension() {
const order = useOrder();

if (!order) {
return null;
}

return (
<Banner status="warning">
Order {order.name} has an outstanding balance. Contact the merchant to
complete your payment.
</Banner>
);
}

Anchor to Return details (render after) ,[object Object]Return details (render after) target

customer-account.order-status.return-details.render-after

Renders after the return details in the return status card on the Order status page. This card only appears when a return has been requested. A separate instance of this extension is rendered for each return.

Use this target to display return processing updates, refund estimates, or supplementary return information for a specific return. This target provides returnId to identify the current return, and gives you access to the Order API and the Cart Lines API.

Support
Components (63)
APIs (28)

Supported components

Available APIs

Examples
import {
reactExtension,
Banner,
useOrder,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.order-status.return-details.render-after',
() => <Extension />,
);

function Extension() {
const order = useOrder();

if (!order) {
return null;
}

return (
<Banner status="info">
Your return for order {order.name} is being processed. Refunds typically
take 5–10 business days to appear on your statement.
</Banner>
);
}

Anchor to Best practicesBest practices

  • Keep content contextual: These extensions render inside payment and return status cards, so content should be directly relevant to the payment or return being displayed.
  • Guard against missing data: Always check that useOrder() (React) or order.current (TS) is defined before rendering order-specific content. The order data loads asynchronously and may be undefined on the initial render.
  • Subscribe to data changes in TS extensions: When using the imperative extension() API, subscribe to order and cost to re-render when data becomes available or changes. Call root.replaceChildren() before re-rendering to avoid duplicate content.
  • Avoid heavy rendering: These targets render inline within the Order status page. Avoid complex layouts or large data fetches that could cause layout shifts. Use Banner or lightweight BlockStack layouts for the best experience.

Anchor to LimitationsLimitations

  • Return card visibility: The return status card only appears when a return has been requested for the order. The customer-account.order-status.return-details.render-after target won't render if no returns exist.
Was this page helpful?