Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Payment

Checkout displays the payment methods available to the buyer, including digital wallets, credit cards, buy-now-pay-later plans, and regional options. Use these targets to add contextual messaging, security details, or incentives based on which methods are available and what the buyer has selected.

Anchor to Use casesUse cases

  • Express checkout promotion: Promote wallet options like Apple Pay or Google Pay when they're available to the buyer.
  • Installment plan details: Display information about deferred payment options when they're offered, such as how the installment plan works.
  • Credit card security: Display encryption assurances or purchase protection details when a credit card is selected, so buyers feel confident entering their card details.
  • Gift card or store credit: Display messaging when gift-card or store-credit payment options are available, such as instructions on how to apply them.

Anchor to Payment targetsPayment targets

Use these targets to add content that helps buyers understand and choose their payment method.

Anchor to Render before payment methods ,[object Object]Render before payment methods target

purchase.checkout.payment-method-list.render-before

Renders before the list of payment methods. Use this target to display messaging that applies to all payment options before the buyer makes a selection.

Read available payment options through useAvailablePaymentOptions() and the buyer's current selection through useSelectedPaymentOptions(). Both update reactively as the buyer interacts with payment choices.

Support
Components (59)
APIs (25)

Supported components

Available APIs

Anchor to Render after payment methods ,[object Object]Render after payment methods target

purchase.checkout.payment-method-list.render-after

Renders below the list of payment methods. Use this target for content that responds to the buyer's payment selection, such as security details or payment-specific messaging.

Support
Components (59)
APIs (25)

Supported components

Available APIs

Anchor to Best practicesBest practices

  • Check payment method availability: Not all payment methods are available to every buyer. Read useAvailablePaymentOptions() to confirm the relevant payment type is offered before displaying type-specific messaging. Without this check, type-specific content can appear for payment methods the buyer can't use.
  • Match target to intent: Use render-before for messaging about available payment options before the buyer selects. Use render-after for content that responds to the buyer's selection, such as security details for a specific payment type.
  • Keep content brief at the payment step: The payment step is where buyers enter sensitive information. Keep content before and after the payment list brief to avoid distracting from the payment flow.
  • Don't recreate native payment UI: Checkout renders each payment method's own interactive UI. Adding buttons, form fields, or selection controls at these targets can confuse buyers about where to complete their payment.

Anchor to LimitationsLimitations

  • Read-only payment selection: The payment targets can read available and selected payment methods but can't modify the payment list, pre-select options, or reorder or hide payment methods. Write operations in these targets are cart-scoped: notes, metafields, discount codes, and gift card codes.
  • Limited payment method data: availablePaymentOptions and selectedPaymentOptions expose handle and type for each option. Provider names, logos, fees, and installment terms aren't available through these properties.
Was this page helpful?