Shopify Dev Helper

Cart

All cart operations target the current store's session. The cart is identified by a token stored in a cookie — no authentication is needed.

• GET /cart.js — Returns the full cart object: items, token, total_price, attributes, note, discount_codes etc.
• POST /cart/add.js — Adds one or more items in a single request. Click + Add item to add another row; × removes a row (minimum one row is always present). Each row has its own Variant ID, Quantity, Properties (key/value pairs), and Selling Plan ID. Body: { items: [{ id, quantity, properties?, selling_plan? }] }. The id field is a variant ID (integer).
• POST /cart/update.js — Bulk-updates quantities by variant ID. Body: { updates: { "variantId": qty } }. Also accepts note and attributes. Set a quantity to 0 to remove that item.
• POST /cart/change.js — Changes a single item by variant ID or line number. Body: { id|line, quantity, properties? }. Use id for variant ID or line for 1-based line index.
• POST /cart/clear.js — Removes all line items. Does not clear the cart note or attributes.
• Clear Attributes — Two-step operation: GET cart to discover existing attribute keys, then POST /cart/update.js with each key set to "". Shopify only clears keys that are explicitly sent.
• Clear Note — POST /cart/update.js with { note: "" }.
• Delete Item Properties — Two-step: GET cart to find the item's property keys, then POST /cart/change.js with each key set to "". Sending properties: {} is ignored by Shopify.
• Discount Codes — POST /cart/update.js with { discount: "CODE" }. Multiple codes are joined with a comma. Clear all codes by sending { discount: "" }.
• Detect from page — A Detect from page button inside each item row auto-fills the Variant ID from the active Shopify tab. Resolution order: ?variant= URL param → input[name="id"] / select[name="id"] → ShopifyAnalytics.meta.selectedVariantId → first variant in ShopifyAnalytics.meta.product.variants.

Product

Fetch product data by handle. The response includes all variants, options, images, pricing, and metafields exposed via the AJAX API.

• GET /products/{handle}.js — Returns the product JSON. The handle is the URL-safe slug shown in the product URL (e.g. my-blue-shirt).
• Detect from page — Reads location.pathname from the active tab and extracts the handle using the pattern /\/products\/([^/?#]+)/. Works on any product page URL.

Recommendations

Fetches AI-powered product recommendations for a given product. Requires the product's numeric ID (not the handle or GID).

• GET /recommendations/products.js — Params: product_id (integer), limit (1–10, default 10), intent (related or complementary).
• related — Products similar to the seed product (same type, tags, vendor).
• complementary — Products often bought together with the seed product. Requires configuring complementary products in Shopify Admin or via the Search & Discovery app.
• Detect from page — Two-step: reads the product handle from the URL, then calls /products/{handle}.js to resolve the numeric product ID.

Predictive Search

Returns autocomplete suggestions as the user types — ideal for live search dropdowns.

• GET /search/suggest.json — Params: q (search query), resources[type] (comma-joined resource types), resources[limit] (1–10), resources[fields] (comma-joined fields to search).
• Resource types: product, article, page, collection, query. Select multiple to search across all of them.
• Fields: title, body, tag, product_type, vendor, author, variants.title, variants.sku, variants.barcode. Leave all unselected to search all fields.

Authentication

The Storefront API requires a public access token — not an Admin API key or private app secret. Configure it in the Config tab. Without a token, the Storefront section is disabled and shows a "Token required" overlay.

• Create a token: How to create a Storefront token →
• Header: Sent as X-Shopify-Storefront-Access-Token on every request.
• Storage: Saved to chrome.storage.local — persists across browser restarts.
• API Version: Format YYYY-MM (e.g. 2026-04). Determines the endpoint: https://<store>/api/<version>/graphql.json. Also configured in the Config tab.

Product & Collection

Fetch product and collection data with fine-grained field selection and metafield support.

• Get Product by handle — Returns title, description, priceRange, variants (with prices and options), and images. Handle is the URL slug (e.g. my-product).
• List Products — Returns the first N products. Configurable limit via the First field.
• Get Collection by handle — Returns collection info and its products (first N).
• List Collections — Returns the first N collections with basic info.
• GID inputs — When fetching by ID, the field shows the GID prefix (gid://shopify/Product/) as a visual label — only type the numeric suffix.
• Detect from page — Reads the product or collection handle from the active tab URL and pre-fills the handle field.

Metafields

Add metafield identifiers to product, collection, article, blog, page, or shop queries to fetch custom field values inline. Toggle the metafields pill in the Fields row to reveal the identifier inputs.

• Each identifier has an optional namespace and a required key. Omit the namespace to let Shopify search all namespaces for the key.
• The query fragment appended is: metafields(identifiers: [{namespace: "ns", key: "key"}]) { value type }
• Requires the unauthenticated_read_metafields storefront access scope on your app.
• Storefront API access must be enabled per field. For each metafield definition, go to Shopify Admin → Settings → Custom data → [Resource] → click the field definition → expand Options → enable Storefront API access. Fields without this toggle enabled will return null even when queried with valid identifiers.

Metaobjects

Query custom structured data you've defined in Shopify Admin → Custom data → Metaobjects.

• Get Metaobject by type + handle — Provide the metaobject type (e.g. author) and handle. Alternatively provide the GID numeric suffix directly.
• List Metaobjects — Returns the first N metaobjects of a given type.
• Requires the unauthenticated_read_metaobjects access scope.
• Storefronts API access must be enabled on the Metaobject definition. Go to Shopify Admin → Settings → Custom data → Metaobjects → click your metaobject type → expand Metaobject options → enable Storefronts API access. Without this, all queries for that type will return empty results or an error.

Blog, Article & Page

Query content resources from your store's online store channel.

• Get Blog — By handle or by GID (numeric suffix). Returns blog info and a list of its articles (title, excerpt, published date).
• Get Article by GID — Fetches a single article by its numeric Storefront ID.
• Get Article by handle — Requires both the blog handle and the article handle.
• Get Page — By handle or by GID (numeric suffix). Returns a static page's title, body HTML, and SEO fields.

Menu

Query navigation menus defined in your Online Store → Navigation settings.

• Get Menu — Provide the menu handle (e.g. main-menu). Returns id, title, handle, items (with nested title, url, and sub-items), and itemsCount.
• Requires a valid Storefront Access Token with the unauthenticated_read_content access scope.

Shop

Fetch store-level metadata from the Storefront API. Useful for reading payment methods, currencies, and primary domain without needing Admin API access.

• Shop Info — Selectable fields include: id, name, description, primaryDomain, paymentSettings, shipsToCountries, currencyCode, moneyFormat, and more (18 fields total).
• Metafields are supported — toggle the metafields pill and add namespace + key identifiers to fetch custom shop-level metafield values inline.

Custom Query

Write any valid Storefront API GraphQL query directly. The token and version from Config are used automatically.

• The Format button reformats your query with consistent indentation.
• The response is shown in the JSON viewer below, with search and expand/collapse controls.
• The query runs against https://<shop>/api/<version>/graphql.json — the same endpoint as all other Storefront tabs.

Customizer

Three buttons that open the Shopify theme editor in a new tab. Each reads window.Shopify.theme.id from the active tab via script injection to resolve the current theme ID.

• Open Customizer — Opens admin.shopify.com/store/<slug>/themes/<id>/editor.
• Code Editor — Opens admin.shopify.com/store/<slug>/themes/<id> (the online code editor for Liquid, CSS, and JS files).
• Open Page in Customizer — Same as Open Customizer, but appends ?previewPath={current pathname} so the customizer opens directly on the page you are viewing.

If Shopify.theme.id cannot be read (e.g. on a non-Shopify page), an error is shown below the buttons.

Current Page

Open in Admin reads ShopifyAnalytics.meta.page.pageType and resourceId from the active tab, then resolves the matching Shopify Admin URL:

• product → /admin/products/<resourceId>
• collection → /admin/collections/<resourceId>
• page → /admin/pages/<resourceId>
• article → fetches <pathname>.js to get the blog_id, then opens /admin/blogs/<blog_id>/articles/<id>
• blog → /admin/blogs/<resourceId>
• Homepage (home / frontPage) → opens the Customizer (no direct Admin page)

Unsupported page types (search, cart, 404) will show an error. Navigate to a product, collection, article, blog, or page first.

Preview Banner

Adds or removes the pb query parameter on the current tab's URL and reloads the page.

• Show Banner (pb=1) — Makes the Shopify storefront preview bar visible.
• Hide Banner (pb=0) — Hides the preview bar.

The preview bar appears when you're browsing a store using a theme preview link. Use this to toggle it without manually editing the URL.

Copy Preview URL

Reads window.Shopify.theme.id from the active tab and appends ?preview_theme_id= to the current page URL, then copies the result to the clipboard.

Use this to share a preview link of an unpublished theme with clients or stakeholders — they can browse the store using your theme without needing Admin access. The link works for anyone and does not expire until the theme is published or deleted.

Page Context Inspector

Injects a script into the active tab's MAIN world and reads Shopify global objects. Useful for debugging theme templates and understanding what data Shopify exposes on each page type.

• ShopifyAnalytics.meta.page — pageType, resourceId, and other analytics metadata set by Shopify on each page load.
• ShopifyAnalytics.meta.product — Product-specific analytics data, available on product pages.
• Shopify.theme — Current theme id, name, and role (published, unpublished, development).
• Shopify.currency — Active currency code and exchange rate.
• Shopify.locale — Active locale string (e.g. en-CA).

Results are displayed in a collapsible key-value table. Arrays show an item count and can be expanded to reveal nested values.

Themes Viewed History

Theme visit history is recorded automatically and documented in the Cache & History section.

Quick Navigation

One-click buttons that open common Shopify Admin sections for the current store in a new tab. The store slug is read from the detected myshopify_domain.

Available links: Dashboard, Products, Collections, Orders, Customers, Themes, Pages, Blog Posts, Files, Metafields & Metaobjects.

Auto-close on non-Shopify pages

When enabled, the extension panel closes automatically after 3 seconds whenever you navigate to a page that is not a Shopify store and there is no active session cache.

• Default: On
• The countdown is shown in the panel ("Closing in 3s…"). Click Close now to dismiss immediately, or open a Shopify tab to cancel the countdown.
• Turn this Off if you want the panel to stay open while you switch between Shopify and non-Shopify tabs.
• This setting has no effect when a session cache is active — the panel always stays open if a Shopify tab is still open in the background.

Storefront Access Token

A public Storefront API token used to authenticate all Storefront API (GraphQL) requests. Without this token the entire Storefront section is disabled and shows a "Token required" overlay.

• How to create: How to create a Storefront token →
• This is a public token — not an Admin API key or private app secret. It is safe to use client-side.
• Header sent: X-Shopify-Storefront-Access-Token: <your-token>
• Stored in chrome.storage.local — survives browser restarts and extension updates.
• Use the Show / Hide button to reveal the token for verification.

Storefront API Version

Determines which Shopify Storefront API release is used for all GraphQL requests. Format: YYYY-MM (e.g. 2026-04).

• Default: 2026-04
• The version is inserted into the endpoint URL: https://<shop>/api/<version>/graphql.json
• Shopify releases a new API version quarterly. Update this value to access new fields and features, or pin it to an older version for backward compatibility.
• Shopify supports the last 12 months of releases. Versions older than that return a deprecation warning and are eventually removed.

How session cache works

Every time you activate a Shopify store tab, the extension saves the store domain and tab ID to chrome.storage.session. This cache persists for the lifetime of the browser session. When you switch to a non-Shopify page (e.g. Google, a localhost app, or the browser settings), the extension checks whether the cached Shopify tab is still open. If it is, the full UI is shown using the cached store data and a cached badge appears next to the shop domain in the header.

CORS & request routing

Shopify AJAX API requests (/cart.js, /products/*.js, etc.) are injected into the target tab via chrome.scripting.executeScript — they run inside the tab's JavaScript context, so they use the Shopify origin. When the cache is active, requests are routed to the cached Shopify tab instead of the currently active tab. This avoids CORS issues that would occur if requests were injected into a non-Shopify page.

Storefront API (GraphQL) calls are made directly from the extension service worker context — Shopify's Storefront API allows CORS from browser extensions, so no tab injection is needed there.

Multi-tab behaviour

If you have multiple Shopify store tabs open, the cache always reflects the most recently activated store. Switching between Shopify tabs updates the cache to the new store instantly. The cached badge disappears whenever the active tab is a confirmed Shopify store.

When the cache clears

The cache is cleared automatically in these cases:

• The cached Shopify tab is closed
• The browser session ends (all windows closed)
• You navigate back to a Shopify store tab — the cache is refreshed to the new live data

If the cache clears while you are on a non-Shopify page, the error screen will appear. Open any Shopify store tab to restore full functionality.

Request History

Every API request made from any tab (Cart, Product, Recommendations, Search, Storefront API) is automatically logged to a persistent history. Entries survive page reloads and browser restarts within the same profile.

• Up to 15 entries are kept in localStorage under request.history; the oldest entry is dropped automatically when the cap is reached.
• The active store's domain is tracked in context — every logged entry records which Shopify store the request was made against.
• Each entry shows: HTTP method badge, endpoint path, store domain, HTTP status code, response time (ms), and a relative timestamp (e.g. "3m ago").
• Clicking an entry expands the full JSON response inline.
• Clear all wipes the entire history.

Themes Viewed History

On each tab load the extension reads window.Shopify.theme via script injection and automatically records the active theme. The history is displayed in the Theme & Admin tab.

• Each entry shows the theme name, theme ID, store domain, and a clickable preview URL (?preview_theme_id= appended).
• The currently active theme is visually highlighted in the list.
• Unpinned history is capped at 10 items; oldest entries are dropped automatically.
• Entries can be pinned — pinned items survive the Clear action and have no cap.
• An empty state is shown when no themes have been visited yet.
• The Clear button removes all unpinned entries while leaving pinned ones intact.