Skip to main content

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 (60)
APIs (29)

Supported components

Available APIs

Examples

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
render(<Extension />, document.body);
};

function Extension() {
const order = shopify.order.value;

if (!order) {
return null;
}

return (
<s-banner tone="warning">
Order {order.name} has an outstanding balance. Contact the merchant to
complete your payment.
</s-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 shopify.returnId to identify the current return, and also gives you access to the Order API and the Cart Lines API.

Support
Components (60)
APIs (29)

Supported components

Available APIs

Examples

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
render(<Extension />, document.body);
};

function Extension() {
const order = shopify.order.value;

if (!order) {
return null;
}

return (
<s-banner tone="info">
Your return for order {order.name} is being processed. Refunds typically
take 5–10 business days to appear on your statement.
</s-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 shopify.order.value is defined before rendering order-specific content. The order data loads asynchronously and may be undefined on the initial render.
  • 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 stack layouts for the best experience.
Was this page helpful?