Entry points

We're upgrading!

Extensions are a more flexible, dynamic, and customizable way to surface your Shop Mini to Shop app users.

For new partners, please use extensions to surface your Shop Mini to Shop app users. New Shop Minis submitted with legacy entry-points will not be approved.

For existing partners, we will communicate with you directly and work with you to migrate your existing Shop Mini to extensions over the coming months.

For more support, please send us an email or send us a message in the #shop-minis channel in the Shopify Partners Slack.

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:

1. Define your entry points upfront when you submit your Shop Mini for review.
2. 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: "your-test-store.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: "your-test-store.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 media

Some entry point types allow setting images or videos. Media must be uploaded to the Shopify CDN via the stagedUploadsCreate and fileCreate mutations in the Shopify Admin API. See those links for general information about uploading media. Note: media uploaded using the Shopify Admin API will appear in the Files page in the merchant's Shopify Admin.

Uploading images already hosted elsewhere

info

This option is only available for images. Videos must be uploaded using the multi-stage process described below.

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 media 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 media from your filesystem

Uploading media 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 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
      fileStatus
    }
    userErrors {
      field
      message
    }
  }
}

Wait for the media to be available on the Shopify CDN either by checking the fileStatus field in the fileCreate mutation or 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
      }
    }
    ... on Video {
      url
      sources {
        format
        url
      }
    }
  }
}

Note that for videos, you can choose an alternative source format for the video. Check your usecase for details but we strongly recommend using HLS (.m3u8) format for videos.

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: "your-test-store.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: "your-test-store.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: "your-test-store.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: "your-test-store.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.