Developer Changelog / New API

With the Intents API,
open Shopify's native file picker

Apps can now bring up the "choose from Shopify's file library" screen with a single API call. There's no need to build your own file-selection UI or send merchants off to a separate screen. The selection comes back as an array of file IDs.

On this page
  1. What this actually lets you do (understand it in 30 seconds)
  2. How it works: the flow from invoke to getting IDs
  3. Minimal code example
  4. Key options for this Intent
  5. Before vs. Intents API comparison
  6. 3 steps to get started
  7. 5 points engineers should know
  8. 3 use cases you can apply to your business
  9. A one-line summary for your pitch

1What this actually lets you do

From your app, pick:shopify/File just calling this new Intent opens Shopify's native file picker.
Merchants pick files from the familiar Shopify file library, and the appreceives the selection as an array of file IDs.

Before: build your own picker

You had to implement your own file-selection UI or send merchants into a separate flow. This meant both implementation cost and a fragmented UX.

Now: just call Shopify's native one

A single API call opens Shopify's file picker. It supports filtering by media type, multiple selection, and pre-selection. Results come back as an array of IDs.

2How it works: the flow from invoke to getting IDs

App App Home / UI Extension intents.invoke() Intent pick:shopify/File Shopify handles it File picker Merchant selects Choose from library response code === 'ok' data.ids = [ ... ] Array of file IDs
What is the Intents API : a mechanism for invoking native Shopify-side actions (here, file selection) from your app as an "intent."
The app shopify.intents.invoke() fires off the intent and, from the returned activity, waits for the complete to receive the result.

3Minimal code example

const activity = await shopify.intents.invoke('pick:shopify/File'); const response = await activity.complete; if (response.code === 'ok') { console.log('Selected file IDs:', response.data.ids); // response.data.ids is an array of the selected file IDs }
The same call works in both App Home (iframe) and UI Extensionsto run.invoke to open the picker,activity.complete and awaitresponse.code === 'ok' and if so, receive response.data.ids — those three lines are the basic form.

4Key options for this Intent

Filter by media type

You can narrow the File Library to show only the media types you need (optional).

Allow multiple selection

You can enable multiple selection. The chosen files are returned together as an array of IDs.

Preselect files

You can have specific files already selected when the picker opens. Handy for edit and replace flows.

ids[]

The result is an array of file IDs

When the selection is complete,response.data.ids the selected file IDs are returned as an array.

The article does not specify the exact media type values usable for filtering, or the precise argument format for preselection and multiple selection. When implementing, check the App Home / UI Extension Intents documentation.

5Traditional vs. Intents API comparison

ItemTraditional (your own picker)Intents API(pick:shopify/File)
File selection UI Custom-built Implement your own picker Native Just call Shopify's built-in one
Merchant experience Tends to push users into a separate flow, breaking the experience Stays within the familiar File Library
Invocation Requires your own state management invoke → complete await
Filtering, multiple selection, preselection All implemented yourself OptionsSpecifiable via options
Selection result Design your own way to pass it around response.data.ids Returned as an array

63 steps to get started

1
invoke

Invoke the Intent

From App Home or a UI Extension shopify.intents.invoke('pick:shopify/File') Call

2

Await complete

On the returned activity, complete await it and receive the merchant's completed selection.

3

Receive the ids

response.code === 'ok' Check, andresponse.data.ids use the array of.

75 points engineers should know

File

1. The new Intent is pick:shopify/File

Passing this string to invoke is the starting point. It expresses the intent to pick files from Shopify's file library.

2. The same call works in both App Home and UI Extensions

It can be used from both App Home (iframe) and UI Extensions with the same call, so you can choose the right context.

3. activity.complete is a Promise

invoke returns an activity, and you complete await it to wait for selection to complete — an async flow. It's easy to design so it doesn't block the UI.

code

4. First check response.code the result

Before using the result, check code === 'ok' It's an API shaped on the assumption that you branch on cancellation and error cases here.

ids[ ]

5. What's returned is an array of IDs (not the files themselves)

response.data.ids What you get back is the selected files' array of IDs. Note that if you need the actual file URLs or metadata, the design is to fetch them separately via the Admin API or similar using those IDs.

83 use cases you can apply to your work

USE CASE 1

Replace a custom app's "image replacement UI" with the native picker

Challenge
In an in-house app for editing product pages or landing pages, you've built a custom file upload/selection UI just for choosing images, and maintenance costs are high.
Approach
From the select button, invoke pick:shopify/File and use Shopify's file library as the selection UI as-is. Keep the returned IDs on the app side.
Impact
Cut the implementation and maintenance of a homegrown picker. Merchants can choose confidently on a familiar screen, so the UX stays stable.
Technical notes
Limiting to image types with the filter options helps prevent mis-selection. The body doesn't state the values, so check the documentation.
Bulk
USE CASE 2

A "batch asset import" flow that leverages multi-select

The problem
In gallery and catalog-generation apps, merchants can only select one item at a time, making it tedious to register large numbers of images.
The solution
Enable the multi-select option and open the picker, letting merchants choose everything in one go.data.ids Pass the resulting array straight into batch processing.
The impact
Drastically fewer steps to register assets. Because results come back as an array, you can feed them directly into your app's loop.
Technical notes
The return value is an array of IDs, so design around fetching each file's URL, size, and so on from the Admin API afterward.
Swap-in
USE CASE 3

An editing experience that "shows the current settings" using pre-selection

The problem
In theme-settings and banner-management apps, it's hard to tell which file is currently assigned, leading to mistakes where the wrong file gets selected.
The solution
Use the pre-selection option to open the picker with the currently assigned file already selected. Merchants only need to change what's different.
The impact
Editing starts from "here's how it is now," reducing mix-up mistakes and making the settings-change flow feel more reassuring.
Technical notes
For the IDs passed to pre-selection, reuse the current values your app already holds as-is. Check the documentation for the required format.

9One-line summary you can use in a pitch

"pick:shopify/File A new API that lets you call up Shopify's native file picker just by invoking an Intent.
Zero custom picker implementation, with support for media filtering, multi-select, and pre-selection — results return as an array of file IDs.
Embed file selection the same way in both App Home and UI Extensions.