---
title: Intercept API
description: The Intercept API registers a callback that checks the cart before checkout or a cash payment before Shopify Point of Sale (POS) adds it. Your callback returns validation findings, which POS displays as required or recommended actions.
api_version: 2026-10
source_url:
  html: https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/contextual-apis/intercept-api
  md: https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/contextual-apis/intercept-api.md
---

# Intercept API

**Feature preview:**

This feature is available only to approved apps and is subject to change.

The Intercept API registers a callback that checks the cart before checkout or a cash payment before Shopify Point of Sale (POS) adds it. Your callback returns validation findings, which Shopify POS displays as required or recommended actions. Staff address the findings in a [resolution target](https://shopify.dev/docs/api/pos-ui-extensions/latest/targets/resolution-targets). For complete examples, follow [Build a cart validation UI extension](https://shopify.dev/docs/apps/build/pos/tutorials/build-cart-validation-extension) and [Build a payment validation UI extension](https://shopify.dev/docs/apps/build/pos/tutorials/build-payment-validation-extension). Before registering an interceptor, declare its event and matching resolution target. See [Configuration rules](#configuration-rules).

### Example use cases

* **Cart checks** (`cartvalidations`): Apply a rule to the whole cart before checkout, such as requiring a note when the cart has a discount.
* **Product checks** (`cartvalidations`): Collect staff input for a specific cart line before checkout.
* **Cash review** (`paymentvalidations`): Recommend that staff review the cash count before accepting payment.

### Supported targets

Register interceptors at this target for the following events:

| Target | Events |
| - | - |
| [`pos.app.ready.data`](https://shopify.dev/docs/api/pos-ui-extensions/latest/targets/app-background) | `cartvalidations`, `paymentvalidations` |

### Methods

Use `shopify.intercept()` in the default entry function of `pos.app.ready.data` to register a callback for a declared event. This method is available only on the app background target. The method returns a function that unregisters the callback. You can register one callback per event in each extension instance, and the callback must return its result synchronously. Returning a `Promise` isn't supported.

A valid empty `operations` array adds no findings.

The app background target adds `shopify.intercept()` for registering validation callbacks.

* **intercept**

  **\<K extends keyof ShopifyInterceptMap>(type: K, interceptor: ShopifyInterceptor\<K>) => () => void**

  **required**

  Register an interceptor for a POS host workflow that can be blocked. Returns a function that unregisters the interceptor.

### ShopifyInterceptMap

Maps POS interceptable workflow names to their corresponding \`Event\` types. Used as the generic type parameter for \`shopify.intercept\`.

* cartvalidations

  The event a \`cartvalidations\` interceptor receives. Carries a snapshot of the POS cart taken when the event was produced.

  ```ts
  CartValidationsEvent
  ```

* paymentvalidations

  The event a \`paymentvalidations\` interceptor receives. Carries the tender attempt's payment method and amount; split payments produce one event per tender, each with its own amount.

  ```ts
  PaymentValidationsEvent
  ```

### CartValidationsEvent

The event a \`cartvalidations\` interceptor receives. Carries a snapshot of the POS cart taken when the event was produced.

* cart

  A snapshot of the POS cart taken when the event was produced.

  ```ts
  Cart
  ```

* type

  The event name, always \`'cartvalidations'\`.

  ```ts
  'cartvalidations'
  ```

### Cart

Represents the shopping cart state, including line items, pricing, customer information, and applied discounts. Provides comprehensive access to all cart data and operations.

* cartDiscount

  The cart-level discount to apply during bulk update. Replaces existing cart discount. Set to \`undefined\` to remove current discount.

  ```ts
  Discount
  ```

* cartDiscounts

  An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array.

  ```ts
  Discount[]
  ```

* currency

  The ISO 4217 currency code for this cart.

  ```ts
  string
  ```

* customer

  The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart.

  ```ts
  Customer
  ```

* editable

  Indicates whether the cart is currently editable. An \`undefined\` value should be treated as \`true\` for backward compatibility. Use this to determine if cart modification operations are allowed.

  ```ts
  boolean
  ```

* grandTotal

  The final total amount including all items, taxes, and discounts, formatted as a currency string.

  ```ts
  string
  ```

* lineItems

  An array of line items to set during bulk update. Completely replaces existing cart contents—removes all current items and adds the provided ones.

  ```ts
  LineItem[]
  ```

* note

  The cart note to set during bulk update. Replaces existing note or sets new note if none exists. Set to \`undefined\` to remove current note.

  ```ts
  string
  ```

* properties

  The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values.

  ```ts
  Record<string, string>
  ```

* subtotal

  The subtotal amount of the cart before taxes and discounts, formatted as a currency string.

  ```ts
  string
  ```

* taxTotal

  The total tax amount for the cart, formatted as a currency string.

  ```ts
  string
  ```

### Discount

Represents a discount applied to a cart or transaction, including amount and description.

* amount

  The discount value to apply. For \`'Percentage'\` type, this represents the percentage value (For example, "10" for 10% off). For \`'FixedAmount'\` type, this represents the fixed monetary amount to deduct from the line item price. Commonly used for discount calculations and displaying the discount value to merchants.

  ```ts
  number
  ```

* currency

  The \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) currency code associated with the location currently active on POS.

  ```ts
  string
  ```

* discountDescription

  A human-readable description of the discount shown to merchants and customers. This typically includes the discount name, promotion details, or discount code (for example, "SUMMER2024", "10% off entire order", "Buy 2 Get 1 Free"). Returns \`undefined\` when no description is provided.

  ```ts
  string
  ```

* type

  The \[discount type]\(https://help.shopify.com/en/manual/discounts/discount-types) applied to this line item. Can be either \`'Percentage'\` for percentage-based discounts or \`'FixedAmount'\` for fixed monetary amount discounts. This determines how the discount amount is calculated and displayed.

  ```ts
  string
  ```

### Customer

Represents basic customer identification information. Contains the customer ID for linking to detailed customer data and enabling customer-specific features.

* id

  The unique numeric identifier for the customer in Shopify's system. This ID is consistent across all Shopify systems and APIs. Used to link this customer reference to the full customer record with complete profile information. Commonly used for customer lookups, applying customer-specific pricing or discounts, linking orders to customer accounts, or integrating with customer management systems.

  ```ts
  number
  ```

### LineItem

Represents an individual item in the shopping cart. Contains product information, pricing, quantity, discounts, and customization details for a single cart entry.

* attributedUserId

  The staff member 'ID' attributed to this line item. Returns 'undefined' if no staff attribution is set. Use for commission tracking and performance analytics.

  ```ts
  number
  ```

* components

  Bundle components for this line item. Only present for \[product bundles]\(/docs/apps/build/product-merchandising/bundles). Each component represents an individual item within the bundle with its own tax information.

  ```ts
  LineItemComponent[]
  ```

* discountAllocations

  An array of discount allocations applied to this line item, providing detailed breakdown of how discounts are distributed. Returns 'undefined' if no allocations exist. Use for enhanced discount tracking and reporting.

  ```ts
  DiscountAllocation[]
  ```

* discounts

  An array of discounts applied to this line item. Empty array if no discounts are active. Use for displaying line item savings and discount details.

  ```ts
  Discount[]
  ```

* hasSellingPlanGroups

  Determines whether this line item has selling plan groups (subscription options) available. Returns 'undefined' if selling plan information is unavailable. Use for displaying subscription options.

  ```ts
  boolean
  ```

* isGiftCard

  Determines whether this line item is a gift card. Gift cards have special handling requirements and business logic. Use for implementing gift card-specific workflows.

  ```ts
  boolean
  ```

* price

  The unit price of the line item. Returns 'undefined' for custom sales without set prices. Use for pricing calculations and displays.

  ```ts
  number
  ```

* productId

  The product 'ID' this line item represents. Returns 'undefined' for custom sales or non-product items. Use for product-specific operations and linking to product details.

  ```ts
  number
  ```

* properties

  The custom key-value properties attached to this line item. Empty object if no properties are set. Use for metadata, customization options, or integration data.

  ```ts
  { [key: string]: string; }
  ```

* quantity

  The quantity of this item in the cart. Always a positive integer. Use for quantity displays, calculations, and inventory management.

  ```ts
  number
  ```

* requiresSellingPlan

  Determines whether this line item requires a selling plan (subscription) to be purchased. Returns 'undefined' if selling plan information is unavailable. Use for implementing subscription-based product handling.

  ```ts
  boolean
  ```

* sellingPlan

  The currently selected selling plan for this line item. Returns 'undefined' if no selling plan is applied. Contains selling plan details including 'ID', name, and delivery intervals. Use for subscription management and recurring purchase functionality.

  ```ts
  SellingPlan
  ```

* sku

  The Stock Keeping Unit (SKU) identifier for this line item. Returns 'undefined' if no SKU is configured. Use for inventory tracking and product identification.

  ```ts
  string
  ```

* taxable

  Determines whether this line item is subject to tax calculations. Use for tax computation, compliance, and pricing displays.

  ```ts
  boolean
  ```

* taxLines

  An array of tax lines applied to this line item, containing tax amounts and rates. Use for detailed tax reporting and compliance.

  ```ts
  TaxLine[]
  ```

* title

  The display title of the line item. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification.

  ```ts
  string
  ```

* uuid

  The unique identifier for this line item within the cart. Use for line item-specific operations like updates, removals, or property modifications.

  ```ts
  string
  ```

* variantId

  The product variant 'ID' this line item represents. Returns 'undefined' for custom sales or non-variant items. Use for variant-specific operations and product details.

  ```ts
  number
  ```

* vendor

  The vendor or brand name for this line item. Returns 'undefined' if no vendor is set. Use for vendor-specific displays and organization.

  ```ts
  string
  ```

### LineItemComponent

Represents a component of a \[product bundle]\(/docs/apps/build/product-merchandising/bundles) line item. Bundle components contain the individual items that make up a bundle, each with their own pricing and tax information.

* discountAllocations

  An array of discount allocations applied to this component, providing a detailed breakdown of how discounts are distributed across bundle components. Returns \`undefined\` if no allocations exist.

  ```ts
  DiscountAllocation[]
  ```

* price

  The price for the custom sale item as currency string. Must be a valid positive amount. Use for non-catalog items and custom pricing.

  ```ts
  number
  ```

* productId

  The unique numeric identifier for the product this component represents, if applicable.

  ```ts
  number
  ```

* quantity

  The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management.

  ```ts
  number
  ```

* taxable

  Determines whether the custom sale item is taxable. Set to \`true\` to apply tax calculations, \`false\` to exempt from taxes.

  ```ts
  boolean
  ```

* taxLines

  An array of tax lines applied to this component.

  ```ts
  TaxLine[]
  ```

* title

  The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly.

  ```ts
  string
  ```

* variantId

  The unique numeric identifier for the product variant this component represents, if applicable.

  ```ts
  number
  ```

### DiscountAllocation

Represents the allocation of a discount to a specific line item.

* allocatedAmount

  The amount of discount allocated.

  ```ts
  MoneyV2
  ```

### MoneyV2

Represents a monetary amount as a string with explicit currency code.

* amount

  The monetary amount as a string.

  ```ts
  string
  ```

* currencyCode

  The ISO currency code (for example, USD, CAD).

  ```ts
  string
  ```

### TaxLine

Represents a tax line applied to an item or transaction.

* enabled

  Whether this tax is currently enabled.

  ```ts
  boolean
  ```

* price

  The tax amount as a Money object.

  ```ts
  Money
  ```

* rate

  The tax rate as a decimal number.

  ```ts
  number
  ```

* rateRange

  The range of tax rates if applicable.

  ```ts
  { min: number; max: number; }
  ```

* title

  The title or name of the tax.

  ```ts
  string
  ```

* uuid

  The unique identifier for this tax line.

  ```ts
  string
  ```

### Money

Represents a monetary amount with currency information.

* amount

  The monetary amount as a number.

  ```ts
  number
  ```

* currency

  The \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) currency code associated with the location currently active on POS.

  ```ts
  string
  ```

### SellingPlan

Represents a selling plan (subscription) associated with a line item, containing delivery schedule and plan identification details.

* deliveryInterval

  The interval of the selling plan. (DAY, WEEK, MONTH, YEAR).

  ```ts
  string
  ```

* deliveryIntervalCount

  The number of intervals between deliveries.

  ```ts
  number
  ```

* digest

  The fingerprint of the applied selling plan within this cart session. Provided by POS. Not available during refund / exchanges.

  ```ts
  string
  ```

* id

  The unique identifier of the selling plan.

  ```ts
  number
  ```

* name

  The name of the POS device.

  ```ts
  string
  ```

### PaymentValidationsEvent

The event a \`paymentvalidations\` interceptor receives. Carries the tender attempt's payment method and amount; split payments produce one event per tender, each with its own amount.

* amount

  The cash amount received for this tender, in presentment currency.

  ```ts
  MoneyV2
  ```

* paymentMethod

  The payment method staff selected.

  ```ts
  InterceptedPaymentMethod
  ```

* type

  The event name, always \`'paymentvalidations'\`.

  ```ts
  'paymentvalidations'
  ```

### InterceptedPaymentMethod

Identifies the payment method being attempted. \`type\` alone identifies singleton methods (for example \`cash\`). \`identifier\` disambiguates method types a shop can have several of (for example custom payment methods) as they become interceptable.

* identifier

  Present when \`type\` alone is ambiguous. Matching is exact on the pair.

  ```ts
  string
  ```

* type

  The kind of payment method being attempted.

  ```ts
  InterceptedPaymentMethodType
  ```

### InterceptedPaymentMethodType

The kind of payment method being attempted.

```ts
'cash'
```

### ShopifyInterceptor

The interceptor callback for a POS interceptable workflow, keyed by the workflow name so the event and its valid validation targets stay paired.

* event

  ```ts
  ShopifyInterceptMap[K]
  ```

returns

```ts
InterceptResult<ValidationTargetMap[K]>
```

### InterceptResult

The result an interceptor returns. An empty \`operations\` list adds no findings from this interceptor and doesn't remove or override findings from other interceptors.

* operations

  The operations to apply. Each operation can add one validation finding.

  ```ts
  Operation<TTarget>[]
  ```

### Operation

A single host operation produced by an interceptor.

* validationAdd

  ```ts
  ValidationAdd<TTarget>
  ```

### ValidationAdd

Adds a validation to the workflow being intercepted.

* handle

  Stable identifier for this validation, namespaced per extension. Each handle must be unique within one \`operations\` array, even across different targets. A result that repeats a handle is rejected. To flag several line items, include the line item \`uuid\` in each handle.

  ```ts
  string
  ```

* level

  \`ERROR\` creates a finding labeled \`Required\` only when blocking is declared and allowed by the store. Otherwise, it creates a finding labeled \`Recommended\`. \`WARNING\` always creates a finding labeled \`Recommended\`.

  ```ts
  ValidationLevel
  ```

* target

  Locates the data the validation applies to; the host decides where it renders. Omitted or unrecognized targets fall back to the event's root scope (\`$.cart\` / \`$.payment\`). The validation still applies, rendered less specifically. Line item uuids are only valid within the event that delivered them: use \`lineItems\[n].uuid\` from this event's cart snapshot, don't cache uuids across events. Bundle components are not addressable; target their parent line.

  ```ts
  TTarget
  ```

### ValidationLevel

The severity of a validation. \`ERROR\` can block the workflow when blocking is declared and allowed by the store. \`WARNING\` never blocks.

```ts
'WARNING' | 'ERROR'
```

### ValidationTargetMap

Maps POS interceptable workflow names to their valid validation targets.

* cartvalidations

  The targets that a \`cartvalidations\` interceptor can return.

  ```ts
  CartValidationTarget
  ```

* paymentvalidations

  The targets that a \`paymentvalidations\` interceptor can return.

  ```ts
  PaymentValidationTarget
  ```

### CartValidationTarget

A target that a \`cartvalidations\` interceptor can use: the whole cart or one cart line item.

```ts
CartTarget | CartLineItemTarget
```

### CartTarget

Targets the whole cart rather than a specific line item.

```ts
'$.cart'
```

### CartLineItemTarget

Targets one cart line item by its \`uuid\` from this event's \`cart\` snapshot, for example \`$.cart.lineItems\['adfd6b06-4a24-4f5f-9f4b-ea21f4432dd4']\`.

```ts
`$.cart.lineItems['${string}']`
```

### PaymentValidationTarget

A target that a \`paymentvalidations\` interceptor can use. The only supported target is the payment attempt.

```ts
"$.payment"
```

### Intercept types

Event names accepted by `shopify.intercept()` and the event each callback receives.

* **cartvalidations**

  **CartValidationsEvent**

  **required**

  The event a `cartvalidations` interceptor receives. Carries a snapshot of the POS cart taken when the event was produced.

* **paymentvalidations**

  **PaymentValidationsEvent**

  **required**

  The event a `paymentvalidations` interceptor receives. Carries the tender attempt's payment method and amount; split payments produce one event per tender, each with its own amount.

### Validation operations

Return this object synchronously from an interceptor. Each operation can add one validation finding.

* **operations**

  **Operation\<TTarget>\[]**

  **required**

  The operations to apply. Each operation can add one validation finding.

Each `handle` must be unique within one result, even when operations target different line items. Shopify POS rejects a result that repeats a handle.

Use one of these exact target tokens to identify where a validation applies.

**`CartValidationTarget | PaymentValidationTarget`**

### CartValidationTarget

* **CartTarget | CartLineItemTarget**

  A target that a `cartvalidations` interceptor can use: the whole cart or one cart line item.

### PaymentValidationTarget

* **"$.payment"**

  A target that a `paymentvalidations` interceptor can use. The only supported target is the payment attempt.

### Examples

* #### Require a note for discounted carts

  ##### Description

  Require staff to record why a cart is discounted before checkout. This example shows how to use \`shopify.intercept('cartvalidations', …)\` to return an \`ERROR\` finding on \`$.cart\` when the cart has a cart-level discount but no note, and no findings otherwise.

  ##### jsx

  ```jsx
  export default function extension() {
    shopify.intercept('cartvalidations', ({cart}) => {
      if (cart.cartDiscounts.length === 0 || cart.note) return {operations: []};

      return {
        operations: [
          {
            validationAdd: {
              level: 'ERROR',
              handle: 'discount-note-required',
              target: '$.cart',
            },
          },
        ],
      };
    });
  }
  ```

* #### Limit line item quantity

  ##### Description

  Limit how many units of an item staff can sell in one cart. This example shows how to use \`shopify.intercept('cartvalidations', …)\` to return an \`ERROR\` finding on each cart line with a quantity over 5, with the line's \`uuid\` in each handle.

  ##### jsx

  ```jsx
  const MAX_QUANTITY = 5;

  export default function extension() {
    shopify.intercept('cartvalidations', ({cart}) => ({
      operations: cart.lineItems
        .filter((line) => line.quantity > MAX_QUANTITY)
        .map((line) => ({
          validationAdd: {
            level: 'ERROR',
            handle: `quantity-limit-${line.uuid}`,
            target: `$.cart.lineItems['${line.uuid}']`,
          },
        })),
    }));
  }
  ```

* #### Recommend a cash count review

  ##### Description

  Recommend that staff count large cash payments. This example shows how to use \`shopify.intercept('paymentvalidations', …)\` to return a \`WARNING\` finding on \`$.payment\` when the cash amount received is 100 or more, and no findings for smaller amounts.

  ##### jsx

  ```jsx
  export default function extension() {
    shopify.intercept('paymentvalidations', ({amount}) => {
      if (Number(amount.amount) < 100) return {operations: []};

      return {
        operations: [
          {
            validationAdd: {
              level: 'WARNING',
              handle: 'cash-count-recommended',
              target: '$.payment',
            },
          },
        ],
      };
    });
  }
  ```

***

## Finding severity

The callback's result and the store's settings determine how Shopify POS displays a finding:

| Callback result | Store configuration | POS label |
| - | - | - |
| `ERROR` | `blocking = true` and the store has turned on **Allow app to block checkout** | **Required** |
| `ERROR` | Blocking isn't declared or the store hasn't allowed it | **Recommended** |
| `WARNING` | Any | **Recommended** |
| Fails: isn't registered, rejects, times out, or returns an invalid or missing result | `blocking = true`, and the store has turned on both **Allow app to block checkout** and **Block checkout if app experiences a problem** | **Required** |
| Fails | Any other configuration | **Recommended** |

Setting `blocking = true` declares that your interceptor can block checkout (`cartvalidations`) or a payment (`paymentvalidations`). It doesn't grant the store's permission. Required findings stop checkout or the payment until staff resolve or skip them through the Shopify POS flow. Recommended findings don't require resolution.

Merchants turn on both settings in the POS editor, in your extension's configuration. For the steps, see [Activate a POS app extension](https://help.shopify.com/en/manual/sell-in-person/getting-started/shopify-pos-from-admin/pos-ui-extensions#action-extensions). **Allow app to block checkout** lets your `ERROR` findings block the workflow. **Block checkout if app experiences a problem** makes the finding that Shopify POS creates for a failed interceptor Required, but only for an intercept that sets `blocking = true`. Despite their labels, both settings apply to cart validations and payment validations.

***

## Execution order

Shopify POS runs your interceptor callback at specific points in each flow, and the order differs by event. The following sections give the sequence for each event: cart validation (`cartvalidations`) and payment validation (`paymentvalidations`).

### Cart validation (`cartvalidations`)

The following steps describe the order in which Shopify POS runs cart validation, from the first cart change through checkout to the resolution target:

1. Changes to the cart run cart validation. Shopify POS clears findings when the cart has no items and no customer. A cart with only a customer still runs validation.
2. Starting checkout runs cart validation again rather than reusing an earlier result. Blocking findings prevent checkout.
3. Staff can tap the cart validation banner to open the cart resolution target. For what happens when staff proceed, see [Revalidation](https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/contextual-apis/resolution-api#revalidation).

### Payment validation (`paymentvalidations`)

The following steps describe the order in which Shopify POS runs payment validation, from a cash payment attempt to the resolution target:

1. Selecting or confirming cash runs payment validation before Shopify POS adds the payment. For split payments, each cash payment attempt runs validation. Retrying a failed payment submission doesn't run validation again.
2. After staff select the cash tendered amount, Shopify POS automatically opens the payment resolution target if your callback returns findings, including Recommended findings. For what happens when staff proceed, see [Revalidation](https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/contextual-apis/resolution-api#revalidation).

***

## Configuration rules

Configure intercepts in `shopify.extension.toml`. The following sections cover the properties you set on each intercept and the requirements your configuration must meet. For complete examples, see Configure intercepts in the [cart validation tutorial](https://shopify.dev/docs/apps/build/pos/tutorials/build-cart-validation-extension#configure-intercepts) and the [payment validation tutorial](https://shopify.dev/docs/apps/build/pos/tutorials/build-payment-validation-extension#configure-intercepts).

### Intercept properties

Each intercept declaration accepts the following properties:

| Property | Required? | Value | Description |
| - | - | - | - |
| `event` | Yes | `string` matching `cartvalidations` or `paymentvalidations` | The Shopify POS workflow to intercept. Declare each event at most once. |
| `blocking` | No | `boolean` | Set to `true` if the callback can return `ERROR` findings. Defaults to `false`. Required findings also need the store's [blocking permission](#finding-severity). |
| `applies_to` | Yes if `event` is `paymentvalidations` | `array` of unique `string` values | The payment methods that trigger the interceptor. Currently supports only `["cash"]`. Don't set this property when `event` is `cartvalidations`, even to an empty array. |

### Configuration requirements

A valid intercept configuration must meet these requirements:

* Use an app whose API client is approved for the POS intercept developer preview. Shopify checks this access when you run `shopify app dev`.
* Add `[[extensions.targeting.capabilities.intercepts]]` to the `[[extensions.targeting]]` entry where `target = "pos.app.ready.data"`. Don't add it under extension-level capabilities.
* Set `runs_offline = true` under `[extensions.supported_features]`.
* Set `api_version` to `2026-10` or a later stable version.
* Declare the matching resolution target for each event, even if it returns only warnings: `pos.cart.validations.resolution.render` for `cartvalidations`, and `pos.payment.validations.resolution.render` for `paymentvalidations`. Each resolution target also requires its matching event declaration in the same extension.
* Shopify rejects unknown fields or events, duplicate events, invalid types or payment method values, and events or resolution targets without a matching declaration.

***

## Best practices

* **Prepare asynchronous data before the callback runs:** The callback must return synchronously, so fetch or subscribe to any data it needs during target setup, cache the result, and read the cached value inside the callback.

***

## Related

[Tutorial - Build a cart validation UI extension](https://shopify.dev/docs/apps/build/pos/tutorials/build-cart-validation-extension)

[Tutorial - Build a payment validation UI extension](https://shopify.dev/docs/apps/build/pos/tutorials/build-payment-validation-extension)

[Reference - Resolution targets](https://shopify.dev/docs/api/pos-ui-extensions/2026-10/targets/resolution-targets)

[Reference - Resolution API](https://shopify.dev/docs/api/pos-ui-extensions/2026-10/target-apis/contextual-apis/resolution-api)

***