---
title: Resolution API
description: The Resolution API reads the cart or payment data for your resolution interface, and registers a save handler to finish pending work before Shopify Point of Sale (POS) revalidates.
api_version: 2026-10
source_url:
  html: https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/contextual-apis/resolution-api
  md: https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/contextual-apis/resolution-api.md
---

# Resolution API

**Feature preview:**

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

The Resolution API reads the cart or payment data for your resolution interface, and registers a save handler to finish pending work before Shopify Point of Sale (POS) revalidates. For an item-targeted authenticity check demo, follow [Build a cart validation UI extension](https://shopify.dev/docs/apps/build/pos/tutorials/build-cart-validation-extension#build-the-resolution-interface).

### Use cases

* **Cart findings**: Derive the cart line that needs attention from the intercepted cart.
* **Payment findings**: Show the attempted payment method and cash amount received.
* **Pending changes**: Run an asynchronous check and save its result before Shopify POS revalidates.
* **Revalidation updates**: Refresh the interface after Shopify POS revalidates.

### Supported targets

Each resolution target receives the following event data:

| Target | Event data |
| - | - |
| [`pos.cart.validations.resolution.render`](https://shopify.dev/docs/api/pos-ui-extensions/latest/targets/resolution-targets#cart-validations-resolution) | `{cart}` |
| [`pos.payment.validations.resolution.render`](https://shopify.dev/docs/api/pos-ui-extensions/latest/targets/resolution-targets#payment-validations-resolution) | `{paymentMethod, amount}` |

Payment resolution has read-only cart access through [`ReadonlyCartApi`](https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/contextual-apis/cart-api). Use `shopify.cart.current` to read the cart and subscribe to changes. You can't modify the cart from this target.

### Properties

The [`shopify` global object](https://shopify.dev/docs/api/pos-ui-extensions/latest#target-apis-define-what-your-extension-does) provides the intercepted event data and a save handler for the active resolution target. Access the following properties on `shopify` to read the cart or payment event and register work that Shopify POS must await before revalidation.

* **event**

  **ReadonlySignalLike\<TEventData>**

  **required**

  The data of the intercepted event this resolution target was opened for. The `value` property provides the current data, and `subscribe` receives Shopify POS revalidation updates.

* **on​Save**

  **(handler: ResolutionSaveHandler) => Promise<() => Promise\<void>>**

  **required**

  Registers a handler that runs when staff advance the resolution flow (Save, Next, or Done). POS awaits the handler before it re-runs the intercepted validation, so use it to commit any pending work, for example cart updates or storage writes, and `await` those calls inside the handler. A rejected promise does not stop the flow; POS still re-runs validation and the interceptor result decides what happens next.

  Only the most recent handler is kept.

### ReadonlySignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern.

* subscribe

  Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.

  ```ts
  (fn: (value: T) => void) => () => void
  ```

* value

  The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.

  ```ts
  T
  ```

### ResolutionSaveHandler

Runs when staff advance the resolution flow. Return a promise to have POS wait for pending work to finish before it re-runs validation.



returns

```ts
void | Promise<void>
```

### Examples

* #### Refresh after revalidation

  ##### Description

  Keep the resolution interface current after Shopify POS revalidates. This example shows how to use \`shopify.resolution.event.subscribe()\` in the cart resolution target to update the number of cart lines after each revalidation.

  ##### jsx

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';
  import {signal} from '@preact/signals';

  const lineCount = signal(0);

  export default async () => {
    lineCount.value = shopify.resolution.event.value.cart.lineItems.length;
    shopify.resolution.event.subscribe(({cart}) => {
      lineCount.value = cart.lineItems.length;
    });
    render(<Extension />, document.body);
  };

  function Extension() {
    return <s-text>Items after revalidation: {lineCount.value}</s-text>;
  }
  ```

* #### Save a note before revalidation

  ##### Description

  Save staff input before Shopify POS revalidates. This example shows how to use \`shopify.resolution.onSave()\` in the cart resolution target to save a note to the first cart line, so your interceptor can read it during revalidation.

  ##### jsx

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';
  import {signal} from '@preact/signals';

  const note = signal('');

  export default async () => {
    await shopify.resolution.onSave(async () => {
      const [line] = shopify.resolution.event.value.cart.lineItems;
      if (!line) return;

      await shopify.cart.addLineItemProperties(line.uuid, {Note: note.value.trim()});
    });
    render(<Extension />, document.body);
  };

  function Extension() {
    return (
      <s-text-field
        label="Note"
        value={note.value}
        onInput={(event) => {
          note.value = event.currentTarget.value ?? '';
        }}
      />
    );
  }
  ```

***

## Revalidation

When staff tap the proceed control in the resolution interface to continue to checkout or complete the payment, Shopify POS runs validation again. The interceptor's findings, not the save handler's return value, decide whether staff can continue. This applies to both resolution targets. When staff proceed:

| Situation | What Shopify POS does |
| - | - |
| The save handler resolves | Runs validation again. The findings decide whether staff can continue. |
| The save handler rejects | Still runs validation again. The rejection doesn't stop the flow. |
| The save handler doesn't finish within 10 seconds | Stops waiting and runs validation again. |
| No save handler is registered | Runs validation again. |

In payment resolution, after staff finish the flow with no [blocking findings](https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/contextual-apis/intercept-api#finding-severity) remaining, Shopify POS resumes the payment. Dismissing the interface doesn't resume it.

***

## Best practices

* **Save the latest change before revalidation:** Await your cart or storage writes inside `shopify.resolution.onSave`, and keep your interceptor returning a finding until the new state is saved. Shopify POS revalidates even if the handler rejects or runs past 10 seconds, so validation can run before a slow save finishes.

***

## 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 - Intercept API](https://shopify.dev/docs/api/pos-ui-extensions/2026-10/target-apis/contextual-apis/intercept-api)

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

***