Entry points

info

Entry points are only available to early access partners. Apply here to join the early access program.

Entry points surface your Shop Mini on product pages and shop pages within the Shop app. This is the primary way users will enter your Shop Mini experience.

Configuring entry points involves two steps:

Define your entry points upfront when you submit your Shop Mini for review.
Set entry point content for specific products or shops that your Shop Mini knows about.

Testing an entry point

As our early access partner, you can test your entry points during development without defining entry point defintions in the manifest.json file. The entry points can be created by setting an entry point defined below.

During development, you can set entry points in your development stores without first submitting entry point definitions for review. These entry points will only be visible to team members or your organization once they sign into their Shop account.

Defining an entry point

Entry points are defined in the manifest.json file for your Shop Mini. They consist of a type and location.

The following example defines a DEFAULT_CARD entry point on the product details page, an IMAGE_COLLECTION_V2 entry point on the store page, a LINK entry point that will be displayed on the store page context menu, and a PRODUCT_OFFER_CARD that will be displayed on the order confirmation page.

{
  "entry_points": [
    {
      "type": "DEFAULT_CARD",
      "location": "PRODUCT_PAGE"
    },
    {
      "type": "IMAGE_COLLECTION_V2",
      "location": "STORE_PAGE"
    },
    {
      "type": "LINK",
      "location": "STORE_PAGE_CONTEXT_MENU"
    },
    {
      "type": "PRODUCT_OFFER_CARD",
      "location": "ORDER_CONFIRMATION_PAGE"
    }
  ]
}

Shop Minis can only define one entry point per type in a given location.

Before you can start setting entry points, you'll need to submit your configuration for review using the CLI.

Entry point types

The entry point type determines its visual style, functionality, and behavior, which can vary from simple links to live events with reminder features.

Type	Description
`LINK`	Displays a simple text link.
`DEFAULT_CARD`	Displays an image, title, text, and action button.
`IMAGE_COLLECTION`	`Deprecated`. Use `IMAGE_COLLECTION_V2` instead. Displays a group of images in a grid or carousel layout.
`IMAGE_COLLECTION_V2`	Displays a group of images in a grid or carousel layout with related products. Included with the Shoppable Posts template.
`VIDEO_COLLECTION`	`Deprecated`. Use `VIDEO_COLLECTION_V2` instead. Displays one or more video previews in a carousel.
`VIDEO_COLLECTION_V2`	Displays one or more video previews in a carousel with related products. Included with the Shoppable Videos template.
`EVENT_CARD_V2`	Displays a preview of a live event and allows the user to sign up for reminder notifications.
`PRODUCT_OFFER_CARD`	Displays a product offer card with a product title, image, discounted price, original price, and an expiration timer.

Entry point locations

The entry point location determines where it will be rendered within the Shop app. However, Shop is responsible for determining the specific placement of entry points on its screens.

Location	Description
`PRODUCT_PAGE`	A product details page within the Shop app.
`STORE_PAGE`	A shop details page within the Shop app.
`ORDER_CONFIRMATION_PAGE`	An order confirmation page within the Shop app. Can only be used with `PRODUCT_OFFER_CARD` type.
`ORDER_MANAGEMENT_PAGE`	An order management page within the Shop app. Can only be used with `PRODUCT_OFFER_CARD` type.
`PRODUCT_PAGE_CONTEXT_MENU`	Context menu on the product details page within the Shop app. Can only be used with `LINK` type.
`STORE_PAGE_CONTEXT_MENU`	Context menu on the shop details page within the Shop app. Can only be used with `LINK` type.

Setting an entry point

Once your entry point definitions have been approved, you can start setting entry points using the Shop Minis Admin API.

Using an owner ID

The entryPointSetByOwner mutation field allows you to set an entry point for a specific shop or product by specifying ownerId. The following example sets the LINK entry point on the STORE_PAGE for the given shop. The shopDomain argument must be for the same shop as the ownerID.

mutation {
  entryPointSetByOwner(
    shopDomain: "shop-minis-sandbox.myshopify.com"
    location: STORE_PAGE_CONTEXT_MENU
    ownerId: "gid://shopify/Shop/68822335510"
    input: {
      link: {
        actionText: "Click me!"
      }
    }
  ) {
    entryPoint {
      id
    }

    userErrors {
      code
      field
      message
    }
  }
}

You can set one entry point per type, location, and owner ID. If you perform the mutation twice for the same type, location, and owner ID, it will update the entry point values.

See EntryPointSetInput for setting other types of entry point.
See EntryPointSetByOwnerUserErrorCode for possible errors.

Using a visibility rule

To make an entry point visible on many products, you can set an entry point with a visibility rule. Visibility rules use a subset of the flexible Shopify search syntax. It supports the equality comparator (:), the AND and OR connectives, and the product id and tag fields. Visibility rules are currently only supported for PRODUCT_PAGE and PRODUCT_PAGE_CONTEXT_MENU entry points.

This example visibility rule matches all products that are tagged "foo" and either "bar" or "baz":

tag:foo AND (tag:bar OR tag:baz)

This example visibility rule matches the products with the id "7922591727871" or with the id "7922600935679":

id:7922591727871 OR id:7922600935679

The following example sets the LINK entry point on the PRODUCT_PAGE for all products matching the provided visibilityRule in the shop specified by the shopDomain argument.

mutation {
  entryPointSetByRule(
    shopDomain: "shop-minis-sandbox.myshopify.com"
    location: PRODUCT_PAGE
    visibilityRule: "tag:foo AND (tag:bar OR tag:baz)"
    input: {
      link: {
        actionText: "Click me!"
      }
    }
  ) {
    entryPoint {
      id
    }

    userErrors {
      code
      field
      message
    }
  }
}

You can set one entry point per type and location using a visibility rule. If you perform the entryPointSetByRule mutation twice for the same type and location, it will update the entry point values, including the visibility rule. The maximum length of a visibility rule can be 20K characters.

If a visibility rule is invalid, this mutation will return an INVALID_VISIBILITY_RULE user error. To obtain more details regarding the invalid rule, use the entryPointVisibilityRuleValidity query field. This field requires a rule argument and returns a status field indicating the validity of the rule as well as a userErrors field that lists any validation issues.

See EntryPointSetInput for setting other types of entry point.
See EntryPointSetByRuleErrorCode for possible errors.

Uploading images

Some entry point types allow setting images. Images must be uploaded to the Shopify CDN via the stagedUploadsCreate and fileCreate mutations in the Shopify Admin API. Note: images uploaded using the Shopify Admin API will appear in the Files page in the merchant's Shopify Admin.

If you are already hosting images elsewhere, you can use the fileCreate mutation directly, passing your external image URL:

mutation {
  fileCreate(files: [{ originalSource: "https://www.example.com/image.jpg" }]) {
    files {
      id
    }
    userErrors {
      field
      message
    }
  }
}

You'll need to wait for the image to be processed before it is available on the Shopify CDN. You can use the ID returned from the mutation above to query for the file directly and fetch the URL:

query {
  node(id: "gid://shopify/MediaImage/123") {
    ... on MediaImage {
      image { url }
    }
  }
}

Uploading an image from your filesystem is a multi-stage process. First, you'll need to create a staged upload target:

mutation {
  stagedUploadsCreate(input: {
    filesize: "1234"
    filename: "foo.jpg"
    mimeType: "image/jpeg"
    resource: IMAGE
  }) {
    stagedTargets {
      url
      resourceUrl
      parameters {
        name
        value
      }
    }
    userErrors {
      field
      message
    }
  }
}

You can then upload the image file using the generated URL and parameters.

Now use the fileCreate mutation with the resourceUrl field from the previous step to create the file in the merchants Files section:

mutation {
  fileCreate(files: [{ originalSource: "<resource-url-from-previous-step>" }]) {
    files {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Wait for the image to be available on the Shopify CDN by using the ID returned in the previous step to query for the uploaded URL:

query {
  node(id: "gid://shopify/MediaImage/123") {
    ... on MediaImage {
      image { url }
    }
  }
}

Fetching entry points

The entryPoints field allows you to paginate through a filtered set of entry points. The following example returns all LINK entry points in the PRODUCT_PAGE location that were updated between the 11th of January and the 22nd of February. As with the "set" mutations above, it is scoped to a given shop via the shopDomain argument.

query {
  entryPoints(
    shopDomain: "shop-minis-sandbox.myshopify.com"
    type: LINK
    location: PRODUCT_PAGE
    updatedAt: {
      min: "2023-01-11"
      max: "2023-02-22"
    }
  ) {
    nodes {
      ... on LinkEntryPoint {
        actionText
      }
    }
  }
}

Unsetting an entry point

The entryPointDeleteByOwner, entryPointDeleteByRule, and entryPointDeleteAll mutation fields allow you to unset entry points.

The following example will remove the LINK entry point from the STORE_PAGE for the given shop. The shopDomain argument must be for the same shop as the ownerID.

mutation {
  entryPointDeleteByOwner(
    shopDomain: "shop-minis-sandbox.myshopify.com"
    type: LINK
    location: STORE_PAGE
    ownerId: "gid://shopify/Shop/68822335510"
  ) {
    userErrors {
      code
      field
      message
    }
  }
}

See EntryPointDeleteByOwnerErrorCode for possible errors.

The following example will remove the LINK entry point from the PRODUCT_PAGE, if it uses a visibility rule.

mutation {
  entryPointDeleteByRule(
    shopDomain: "shop-minis-sandbox.myshopify.com"
    location: PRODUCT_PAGE
    type: LINK
  ) {
    userErrors {
      code
      field
      message
    }
  }
}

See EntryPointDeleteByRuleErrorCode for possible errors.

The following example will remove all entry points for the given shop. Deletion will happen asynchronously, so entry points may still be visible for a period after performing this mutation.

mutation {
  entryPointDeleteAll(
    shopDomain: "shop-minis-sandbox.myshopify.com"
  ) {
    userErrors {
      code
      field
      message
    }
  }
}

See EntryPointDeleteAllErrorCode for possible errors.

Accessing entry point context

The useMinisParams hook provides access to useful context from the entry point that launched the Shop Mini.

import {useMinisParams} from '@shopify/shop-minis-platform-sdk'

export const MyScreen = () => {
  const {entryPoint, entryPointParams} = useMinisParams()
}

`entryPoint`

Name	Value
`location`	`EntryPointLocation`
`collectionItems`	An array of image collection entry point items or video collection entry point items

`entryPointParams`

Name	Value	Notes
`shopGID`	`"gid://shopify/Shop/123"`
`productGID`	`"gid://shopify/Product/123"`	Only for `PRODUCT_PAGE` or `PRODUCT_PAGE_CONTEXT_MENU` location.
`productVariantGID`	`"gid://shopify/ProductVariant/123"`	Only for `PRODUCT_PAGE` location. Only when a variant is selected.
`orderGID`	`"gid://shopify/Order/123"`	Only for `ORDER_CONFIRMATION_PAGE` or `ORDER_MANAGEMENT_PAGE` location.
`externalId`	`String`	Partner reference for individual items in entry points such as image collection and video collection
`shopDomain`	`String`	Only for `STORE_PAGE`. Merchant shop domain such as "hello-world.myshopify.com"

Mocking entryPointParams during development

If you want to test your Mini using different entry point parameters, you can create a file named entry-point-params.json in the root directory of your project and set different values using the following shape:

{
  "product_id": "XYZ",
  "shop_id": "XYZ",
  "product_variant_id": "XYZ",
  "external_id": "XYZ",
  "shop_domain": "XYZ",
  "order_id": "XYZ"
}

The next time you open your Mini using the CLI, these values will be returned by the hook useMinisParams.

Testing an entry point​

Defining an entry point​

Entry point types​

Entry point locations​

Setting an entry point​

Using an owner ID​

Using a visibility rule​

Uploading images​

Fetching entry points​

Unsetting an entry point​

Accessing entry point context​

entryPoint​

entryPointParams​

Mocking entryPointParams during development​