Shop actions

The React Native SDK will allow Shop Minis to trigger existing Shop actions. Instead of building existing actions such as “favoriting”, “unfavoriting”, and “add product to bag”, Shop Minis must use the ones from the Shop app. These Shop actions can be triggered by using the useShopActions hook.

const shopActions = useShopActions()

This hook will return an object with all the available actions that you can use.

Each Shop action will return a Promise with a ShopActionResult object, which can either be a ShopActionOk or a ShopActionError, depending if the operation was completed successfuly or not. This ShopActionResult will look like this:

{
  ok: boolean
  data?: T
  error?: Error
}

Where ok tells us if the action was successful or not. If it returns true you can use data if any was returned from the action. Otherwise, if it's false, an Error instance will be present in the error property.

Favorite a product

Favoriting a product can be done using the following Shop action. It requires three parameters.

const actionResult = await shopActions.favorite({
  shopId: 'gid://shopify/Shop/1234567890',
  productId: 'gid://shopify/Product/1234567890',
  productVariantId: 'gid://shopify/ProductVariant/1234567890',
})

Unfavorite a product

Unfavoriting a product can be done using the following Shop action. It requires three parameters.

const actionResult = await shopActions.unfavorite({
  shopId: 'gid://shopify/Shop/1234567890',
  productId: 'gid://shopify/Product/1234567890',
  productVariantId: 'gid://shopify/ProductVariant/1234567890',
})

Follow a store

Following a store can be done using the Shop action below. It requires one parameter:

const actionResult = await shopActions.followShop({
  shopId: 'gid://shopify/Shop/1234567890'
})

Unfollow a store

Unfollowing a store can be done using the Shop action below. It requires one parameter:

const actionResult = await shopActions.unfollowShop({
  shopId: 'gid://shopify/Shop/1234567890'
})

Attribute an existing order

The createOrderAttribution action allows you to initiate the attribution process when your Shop Mini adds an item to an existing order. Orders created through your Shop Mini will be automatically attributed, but if you add a line item to an existing order (e.g. post-purchase upsell) you must manually call createOrderAttribution. You should do this before adding the line item to the order or presenting the payment screen to the user. The attribution will only activate once the payment is processed. See also: Attribution.

const actionResult = await shopActions.createOrderAttribution({
  orderId: 'gid://shopify/Order/123',
  productVariantId: 'gid://shopify/ProductVariant/42',
})

You can optionally attach custom attribution data:

await shopActions.createOrderAttribution({
  orderId: 'gid://shopify/Order/123',
  productVariantId: 'gid://shopify/ProductVariant/42',
  attribution: {
    sourceName: 'foo',
    sourceIdentifier: 'abc123',
  },
})

Open the Product Detail Page

The navigateToProduct Shop action will launch the in-built Shop product detail screen (PDP). The PDP will slide on top of the Shop Mini.

const actionResult = await shopActions.navigateToProduct({
  productId: 'gid://shopify/Product/1234567890',
  // The variant id is optional in this context.
  // If not provided, the PDP will render the default variant.
  productVariantId: 'gid://shopify/ProductVariant/1234567890',
})

Start a checkout process

The navigateToCheckout Shop action will launch the in-built Shop checkout process. This Shop action can start checkout for a given shop's shopping bag or a given payment URL.

To start checkout for a given shop, pass the shop ID in action params. For example:

const actionResult = await shopActions.navigateToCheckout({
  shopId: 'gid://shopify/Shop/1234567890',
})

To pass a discount code to checkout, add discountCode to the action params.

const actionResult = await shopActions.navigateToCheckout({
  shopId: 'gid://shopify/Shop/1234567890',
  discountCode: 'FREESHIPPING',
})

To start checkout for a given payment URL, pass the URL in action params. For example:

const actionResult = await shopActions.navigateToCheckout({
  url: 'https://shop-minis-testing.myshopify.com/1234/order_payment/5678?secret=abcd1234',
})

Buy a product

The buyProduct Shop action requires three parameters.

const actionResult = await shopActions.buyProduct({
  productId: 'gid://shopify/Product/1234567890',
  productVariantId: 'gid://shopify/ProductVariant/1234567890',
  quantity: 1,
})

There is also a fourth, optional parameter called "attribution" that allows you to add metadata to a product variant that is being purchased. See also: Attribution of line items

const actionResult = await shopActions.buyProduct({
  productId: 'gid://shopify/Product/1234567890',
  productVariantId: 'gid://shopify/ProductVariant/1234567890',
  quantity: 1,
  attribution: {
    sourceName: 'some useful category',
    sourceIdentifier: 'some interesting id that is associated with this event.',
  },
})

Attribution of line items

The actions navigateToProduct and buyProduct allow optional line item attribution data to be set on them. This allows a Shop Mini developer to tag items that are purchased via their Shop Mini with some custom attributes that allow that order to be identified by the developer. The attribution has the following shape:

{
  sourceName: "some useful category",
  sourceIdentifier: "some interesting id that is associated with this event.",
}

The sourceName and sourceIdentifier are both required parameters and are free form - the Shop Mini developer is free to put any string value in there that suits their usecase. It is recommended, however, that sourceName be used to categorize the attribution and sourceIdentifier be used for specific information about the attribution. For example:

{
  sourceName: "purchsed-through-product-recommendations",
  sourceIdentifier: "123456",
}

This attribution shows that the product was purchased through a particular part of a Shop Mini that gives product recommendations and the particular recommendation is identified by its unique id 123456.

Error handling

When your Shop Mini reaches a recoverable or non-recoverable error state, you can use the actions showErrorToast or showErrorScreen to send feedback to the user.

Toast

showErrorToast displays a toast at the bottom of the screen with an error theme UI. It accepts an optional param to customise the error message (defaults to "Something went wrong")

Error screen

showErrorScreen will present a new screen that takes over the UI and won't allow the user to go back to the previous flow. This screen presents a title, description and a button to close the Shop Mini. Both message and title are customisable via params (message defaults to "Something has gone wrong and we are unable to load what you are looking for." and title defaults to "Whoops!").