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',
})

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',
  // Optional.
  discountCode: '20OFF',
  // Optional, see "Attribution of line items" below.
  attribution: {
    sourceName: 'my-mini-recommendation',
    sourceIdentifier: '123456',
  },
})

Open the Store Page

The navigateToShop Shop action will open the specified store.

const actionResult = await shopActions.navigateToShop({
  shopId: 'gid://shopify/Product/1234567890',
  shopName: 'My Shop',
})

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 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',
})

Open an order

The navigateToOrder Shop action will open the specified order.

const actionResult = await shopActions.navigateToOrder({
  orderId: 'gid://shopify/Order/1234567890',
})

Buy products

The buyProducts Shop action requires three parameters.

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

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

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

Attribution of line items

The actions navigateToProduct and buyProducts 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.

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',
  },
})

Close the Shop Mini

The closeMini Shop action allows the Shop Mini to close itself programmatically. This might be used after a successful operation or when an unrecoverable error occurs and the mini app needs to shut down gracefully.

const actionResult = await shopActions.closeMini()

This action does not require any parameters. When invoked, it will attempt to close the Shop Mini and return a ShopActionResult object indicating the success or failure of the operation.

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")

const actionResult = await shopActions.showErrorToast({
  message: 'Optional custom error message',
})

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!").

const actionResult = await shopActions.showErrorScreen({
  title: 'Optional custom title',
  message: 'Optional custom error message',
})

Get Shop app information

The getShopAppInformation Shop action asynchronously returns the app's version number, build number and build ID.

const actionResult = await shopActions.getShopAppInformation()