useResolveIntent

The useResolveIntent hook completes the intent that your Mini is handling and sends the result back to the Shop app. Pair it with useIntent to read the incoming intent, then resolve it with an ok, error, or closed result.

Pass the intent key to useResolveIntent so TypeScript can narrow the result data to the intent's contract.

Anchor to useResolveIntent
useResolveIntent(
intentKey
)

Anchor to useResolveIntent-parametersParameters

Anchor to intentKey intentKey K extends required

Anchor to useResolveIntent-returnsReturns

IntentKey

keyof IntentDefinitions

IntentDefinitions

addToCartProductVariant

{ action: "add_to_cart"; type: "shopify/ProductVariant"; data: AddToCartProductVariantParams; result: AddToCartProductVariantResult; }

buyNowProductVariant

{ action: "buy_now"; type: "shopify/ProductVariant"; data: BuyNowProductVariantParams; result: BuyNowProductVariantResult; }

createUserImage

{ action: "create"; type: "shop/UserImage"; data: CreateUserImageParams; result: ImageUrlResponse; }

selectProductVariant

{ action: "select"; type: "shopify/ProductVariant"; data: SelectProductVariantParams; result: SelectProductVariantResult; }

tryOnProduct

{ action: "try_on"; type: "shopify/Product"; data: TryOnProductParams; result: ImageUrlResponse; }

AddToCartProductVariantParams

Data payload for the `add_to_cart:shopify/ProductVariant` intent. Adds a variant to the user's cart. If `productVariantId` is omitted (or `forceShow` is `true`), the host opens the same native variant selector sheet as `select:shopify/ProductVariant` first — the user picks a variant and quantity, and the host then performs the add-to-cart on confirm. For products outside Shop's catalog (referral products), the host navigates the user to the product's PDP instead of adding to cart.

discountCodes
Discount codes to apply to the cart when adding.
```
string[]
```
forceShow
When `true`, always render the sheet — even for products with a single variant or when `productVariantId` is supplied. Bypasses the single-variant short-circuit so the mini gets a consistent confirmation step. Defaults to `false`.
```
boolean
```
includedProductVariantGIDs
Optional allow-list of variant GIDs. When set, only these variants are presented to the user. Other variants are filtered out before the option tree is built. Ignored when `productVariantId` is supplied.
```
string[]
```
initialQuantity
Initial quantity displayed in the stepper. Defaults to `quantity ?? 1`.
```
number
```
initialVariantId
If present, the GID of the variant that should be initially highlighted in the sheet. Defaults to the product's default variant. Ignored when `productVariantId` is supplied.
```
string
```
maxQuantity
Maximum quantity selectable in the stepper. Defaults to the variant's `quantityAvailable` (or unbounded when stock is not tracked).
```
number
```
productId
The GID of the product. E.g. `gid://shopify/Product/123`.
```
string
```
productVariantId
The GID of the variant to add. When provided, the host adds it directly without showing the sheet. Omit to let the user pick.
```
string
```
quantity
Quantity to add. Defaults to `1`.
```
number
```
showQuantity
Whether to show the quantity stepper. Defaults to `true`.
```
boolean
```

AddToCartProductVariantResult

Successful payload returned from `add_to_cart:shopify/ProductVariant`. Discriminate via `data.outcome`: - `'added_to_cart'` — a concrete variant was added; selection fields (`productVariantId`, `quantity`, `source`) are present. - `'navigated_to_product'` — the host could not add this product (e.g. referral product on another merchant's storefront) and instead sent the user to the PDP. Only `productId` is present.

AddToCartAddedResult | AddToCartNavigatedToProductResult

AddToCartAddedResult

Variant added to the cart by `add_to_cart:shopify/ProductVariant`.

outcome
Discriminator. The host added a concrete variant to the cart.
```
'added_to_cart'
```
productVariantId
The GID of the variant the user picked.
```
string
```
quantity
The quantity the user chose in the stepper. `1` when the stepper is hidden.
```
number
```
source
Indicates whether the user actively picked a variant in the sheet (`'user'`) or whether the host resolved the selection automatically without showing UI (`'auto'`). `'auto'` is returned when the product has a single selectable variant and `forceShow` is `false` (the default). `'user'` is returned in every other success case — i.e. the sheet was rendered and the user tapped the CTA.
```
'auto' | 'user'
```
variant
The full variant the user picked.
```
ProductVariant
```

ProductVariant

availableForSale
Whether the variant can be purchased. When `false`, calls to add the variant to cart or buy it through the SDK will fail. UI should be gated on this flag. May be `undefined` if the variant was sourced from an API that does not expose stock state.
```
boolean
```
compareAtPrice
```
Money | null
```
id
```
string
```
image
```
ProductImage | null
```
isFavorited
```
boolean
```
price
```
Money
```
selectedOptions
The (name, value) pairs of product options this variant corresponds to. E.g. `[{name: 'Color', value: 'Green'}, {name: 'Size', value: 'M'}]`. Optional for backwards compatibility with variants returned by older Shop app hosts; treat as `[]` when undefined.
```
ProductSelectedOption[]
```
title
```
string
```

Money

amount
```
Decimal
```
currencyCode
```
CurrencyCode
```

Decimal

string

CurrencyCode

'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KID' | 'KMF' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STD' | 'STN' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VED' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XOF' | 'XPF' | 'XXX' | 'YER' | 'ZAR' | 'ZMW'

ProductImage

altText
```
string | null
```
height
```
number | null
```
id
```
string | null
```
sensitive
```
boolean | null
```
thumbhash
```
string | null
```
url
```
string
```
width
```
number | null
```

ProductSelectedOption

A single (name, value) pair that identifies which value of a product option a variant corresponds to. E.g. `{name: 'Color', value: 'Green'}`.

name
```
string
```
value
```
string
```

AddToCartNavigatedToProductResult

Returned when the product cannot be added to the cart from the mini (e.g. referral products outside Shop's catalog) and the host instead sent the user to the product's PDP. The mini should treat this as a successful hand-off — the shopper is now on the PDP.

outcome
Discriminator. The host navigated the user to the PDP instead.
```
'navigated_to_product'
```
productId
GID of the product the host navigated to.
```
string
```

BuyNowProductVariantParams

Data payload for the `buy_now:shopify/ProductVariant` intent. Sends the user to express checkout for a variant, bypassing the cart. If `productVariantId` is omitted (or `forceShow` is `true`), the host opens the same native variant selector sheet as the other variant intents — the user picks a variant and quantity, and the host then creates the checkout on confirm. For products outside Shop's catalog (referral products), the host navigates the user to the product's PDP instead.

discountCode
Discount code to apply to the checkout.
```
string
```
forceShow
When `true`, always render the sheet — even for single-variant products or when `productVariantId` is supplied. Defaults to `false`.
```
boolean
```
includedProductVariantGIDs
Allow-list of variant GIDs surfaced in the sheet.
```
string[]
```
initialQuantity
Initial quantity in the stepper. Defaults to `quantity ?? 1`.
```
number
```
initialVariantId
Variant initially highlighted in the picker.
```
string
```
maxQuantity
Max quantity selectable in the stepper.
```
number
```
productId
The GID of the product. E.g. `gid://shopify/Product/123`.
```
string
```
productVariantId
The GID of the variant to buy. When provided, the host creates the checkout directly without showing the sheet. Omit to let the user pick.
```
string
```
quantity
Quantity to buy. Defaults to `1`.
```
number
```
showQuantity
Whether to show the quantity stepper. Defaults to `true`.
```
boolean
```

BuyNowProductVariantResult

Successful payload returned from `buy_now:shopify/ProductVariant`. Discriminate via `data.outcome`: - `'checkout_opened'` — express checkout opened for a concrete variant; selection fields (`productVariantId`, `quantity`, `source`) are present. - `'navigated_to_product'` — the host could not buy this product (e.g. referral product on another merchant's storefront) and instead sent the user to the PDP. Only `productId` is present.

BuyNowCheckoutOpenedResult | BuyNowNavigatedToProductResult

BuyNowCheckoutOpenedResult

Checkout opened for a concrete variant by `buy_now:shopify/ProductVariant`.

outcome
Discriminator. The host opened express checkout for a variant.
```
'checkout_opened'
```
productVariantId
The GID of the variant the user picked.
```
string
```
quantity
The quantity the user chose in the stepper. `1` when the stepper is hidden.
```
number
```
source
Indicates whether the user actively picked a variant in the sheet (`'user'`) or whether the host resolved the selection automatically without showing UI (`'auto'`). `'auto'` is returned when the product has a single selectable variant and `forceShow` is `false` (the default). `'user'` is returned in every other success case — i.e. the sheet was rendered and the user tapped the CTA.
```
'auto' | 'user'
```
variant
The full variant the user picked.
```
ProductVariant
```

BuyNowNavigatedToProductResult

Returned when the product cannot be bought from the mini (e.g. referral products outside Shop's catalog) and the host instead sent the user to the product's PDP. The mini should treat this as a successful hand-off.

outcome
Discriminator. The host navigated the user to the PDP instead.
```
'navigated_to_product'
```
productId
GID of the product the host navigated to.
```
string
```

CreateUserImageParams

camera
Which camera to default to when the camera is used. Defaults to 'front'.
```
'front' | 'rear'
```
crop
Cropping configuration. Omit to skip the cropping step — the user's original photo is returned as-is (capped by `maxSize`).
```
{ aspectRatio?: { width: number; height: number; }; shape?: "rectangle" | "circle"; }
```
maxSize
Max width/height of the output image in pixels. Defaults to 700.
```
number
```
source
If set, skip the source chooser and open this source directly. When omitted, the host shows a sheet letting the user pick a source.
```
'camera' | 'library'
```
tag
Tag identifying the image in the mini's image library. Required so a future saved-images intent can surface previously created images by tag.
```
string
```

ImageUrlResponse

imageUrl
URL of the generated image.
```
string
```

SelectProductVariantParams

Data payload for the `select:shopify/ProductVariant` intent. Prompts the user to pick a variant (and quantity) for the product whose GID is passed as `data.productId`. The host renders a native bottom sheet over the mini WebView using the same option pickers as the Shop PDP. Single-variant products short-circuit without showing UI.

allowOutOfStockSelection
When `true`, the sheet's confirm CTA stays enabled even for a sold-out variant — the host hands the selection back to the mini without touching the cart. Defaults to `true` for the `select` intent so flows like “notify me when back in stock” can pick a sold-out variant. Pass `false` to restore the cart-style sold-out guard.
```
boolean
```
forceShow
When `true`, always render the sheet — even for products with a single variant. The single-variant short-circuit (resolving instantly without showing UI) is bypassed. Useful for flows that want a consistent confirmation step regardless of variant count. Defaults to `false`.
```
boolean
```
includedProductVariantGIDs
Optional allow-list of variant GIDs. When set, only these variants are presented to the user. Other variants are filtered out before the option tree is built.
```
string[]
```
initialQuantity
Initial quantity displayed in the stepper. Defaults to `1`.
```
number
```
initialVariantId
If present, the GID of the variant that should be initially highlighted. Defaults to the product's default variant.
```
string
```
maxQuantity
Maximum quantity selectable in the stepper. Defaults to the variant's available inventory (or unbounded when stock is not tracked).
```
number
```
productId
The GID of the product whose variants should be selectable. E.g. `gid://shopify/Product/123`.
```
string
```
showQuantity
Whether to show the quantity stepper. Defaults to `false` for the `select` intent (selection is informational; quantity is rarely relevant). Pass `true` to opt into the stepper.
```
boolean
```

SelectProductVariantResult

Successful payload returned from `select:shopify/ProductVariant`. The intent result is `{code: 'ok', data: SelectProductVariantResult}` on success; `{code: 'closed'}` when the user dismisses the sheet. The `outcome` discriminator is single-valued today and is preserved for forward-compatibility — the variant-picker intents (`add_to_cart`, `buy_now`) use the same field to discriminate between multiple success outcomes (e.g. cart added vs. navigated to PDP), and minis can use a single switch over `data.outcome` to handle every intent.

outcome
Discriminator. Currently always `'selected'`.
```
'selected'
```
productVariantId
The GID of the variant the user picked.
```
string
```
quantity
The quantity the user chose in the stepper. `1` when the stepper is hidden.
```
number
```
source
Indicates whether the user actively picked a variant in the sheet (`'user'`) or whether the host resolved the selection automatically without showing UI (`'auto'`). `'auto'` is returned when the product has a single selectable variant and `forceShow` is `false` (the default). `'user'` is returned in every other success case — i.e. the sheet was rendered and the user tapped the CTA.
```
'auto' | 'user'
```
variant
The full variant the user picked.
```
ProductVariant
```

TryOnProductParams

variantId
Variant the user selected on the PDP that launched the Mini.
```
string
```

UseResolveIntentReturn

resolveIntent
Completes the intent and returns the user to Shop. Use `{code: 'ok', data: ...}` when the intent succeeds, `{code: 'error', message}` when your Mini cannot complete it, or `{code: 'closed'}` when the user exits without finishing. The returned promise resolves when the result has been sent, and rejects if the SDK could not send it.
```
UseResolveIntentResolver<K>
```

UseResolveIntentResolver

IntentResult

Discriminated union of all possible intent completion outcomes. - `'ok'` — workflow completed successfully with typed result data - `'error'` — workflow failed with a message - `'closed'` — user dismissed without completing

IntentResultOk<T> | IntentResultError | IntentResultClosed

IntentResultOk

Successful intent completion. `data` follows the declared response type: `void` → omitted, concrete shape → required, untyped (`unknown`) → optional.

unknown extends T
  ? {code: 'ok'; data?: T}
  : [T] extends [void]
    ? {code: 'ok'}
    : {code: 'ok'; data: T}

IntentResultError

code
```
'error'
```
message
```
string
```

IntentResultClosed

code
```
'closed'
```

Examples

tsx

import {useCallback} from 'react'

import {Button, useIntent, useResolveIntent} from '@shopify/shop-minis-react'

export default function TryOnResult() {

const {query} = useIntent()

const {resolveIntent} = useResolveIntent('tryOnProduct')

const handleUseImage = useCallback(async () => {

try {

await resolveIntent({

code: 'ok',

data: {imageUrl: 'https://cdn.shopify.com/tryon/example.jpg'},

})

} catch (resolveError) {

console.error('Could not resolve intent:', resolveError)

}

}, [resolveIntent])

const handleClose = useCallback(async () => {

try {

await resolveIntent({code: 'closed'})

} catch (resolveError) {

console.error('Could not close intent:', resolveError)

}

}, [resolveIntent])

if (!query) return null

if (query.action !== 'try_on' || query.type !== 'shopify/Product') {

return null

}

return (

<div>

<p>Use this image for {query.value ?? 'this product'}.</p>

<Button onClick={handleUseImage}>Use image</Button>

Cancel

</Button>

</div>

)

}