--- name: shopify-top-products description: "Mondays: last week's best-selling Shopify products by revenue and units, what moved against the week before, and which top sellers are low on stock. Use when the user asks for this, or when it runs on a schedule." --- # Shopify top products this week Mondays: last week's best-selling Shopify products by revenue and units, what moved against the week before, and which top sellers are low on stock. Knowing what sold last week decides what goes in this week's email, which ad gets the budget and what to reorder. Shopify's product report answers it, once you set the date range, pick the right columns and remember what the week before looked like. The agent ranks last week's products by revenue, puts the previous week next to each, and points out newcomers and big movers. It also checks stock on the leaders, because the product that doubled its sales is usually the next one to run out. ## Two ways to get the data Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used. ## Route A: API or MCP server ### What you need - Admin API access to the store with `read_orders` and `read_products`: a Shopify connector or MCP server, or a custom app token in `SHOPIFY_ADMIN_TOKEN`. If something is missing, say what and stop; do not invent numbers. ### Steps 1. **Pull last week's orders** (Shopify): Query `orders` created from Monday 00:00 to Sunday 24:00 in the shop's timezone, with `test`, `cancelledAt` and `lineItems(first: 100) { nodes { currentQuantity discountedTotalSet { shopMoney { amount } } product { id title totalInventory } } }`. 2. **Pull the week before** (Shopify): Run the same query for the previous Monday to Sunday, so every product has two weeks to compare. 3. **Rank the products**: Skip test and canceled orders, group by product, sum `currentQuantity` and `discountedTotalSet`, and rank by revenue. Note each product's change against the week before and mark newcomers to the top five. 4. **Check stock on the leaders**: For each top-five product, divide `totalInventory` by last week's average daily units. Anything under 14 days gets a line in the report. 5. **Write the report**: The top five with units, revenue and change, their share of the week's sales, the biggest riser and faller further down the list, and the stock warnings. ## Route B: the browser ### What you need - Signed in to Shopify as the owner or staff with **Reports** and **Products** permissions, with the right store picked. If something is missing, say what and stop; do not invent numbers. ### Steps Start at https://admin.shopify.com/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears. 1. **Open Sales by product for last week**: Open the store from admin.shopify.com, then **Analytics > Reports > Sales by product**. Set the date picker to **Last week** (Monday to Sunday) and **Compare to: Previous period**, and sort by **Net sales** descending. 2. **Read the top five and the movers**: For the first five rows take **Net items sold**, **Net sales** and the change column. Note any product that was not in the top five in the comparison period. Scan the rest of the list for the biggest rise and fall in net sales. 3. **Get the week's total**: Read **Net sales** in the report's summary row, or open **Sales over time** for the same range, to work out the top five's share. 4. **Check stock on the leaders**: Go to **Products**, search each top-five product and read **Inventory** on the product list (the total across variants). Divide by last week's units per day; anything under 14 days gets a warning. Note: This is a case where the browser route is the easier one: the Sales by product report already shows the comparison. It reports products, not variants; switch to the Sales by product variant SKU report when colors or sizes matter. Returns are dated to the refund, so a week's net sales can differ slightly from the API route. ## The report - **Top products** by revenue: units, revenue, change against the week before. - Their share of the week's total sales. - Newcomers to the top five, and the biggest riser and faller outside it. - Top sellers with less than two weeks of stock. ## Post it to Briefkin When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on. ```bash [ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \ -H "authorization: Bearer $BRIEFKIN_TOKEN" \ -H "content-type: application/json" \ -d @- <<'JSON' { "v": 1, "event_id": "shopify-top-products/", "item_key": "shopify-top-products", "project": "Acme Store", "source": "Shopify top products this week skill", "kind": "update", "title": "Linen tote led the week with $8,268", "summary": "The top 5 products made **$19,261**, 46% of the week's **$41,880** in sales. Canvas apron is new to the top 5.", "widget": [ { "type": "Table", "props": { "columns": [ "Product", "Units", "Revenue", "vs last week" ], "align": [ "left", "right", "right", "right" ], "rows": [ [ "Linen tote", 212, "$8,268", "+18%" ], [ "Ceramic mug", 154, "$3,696", "+6%" ], [ "Wool throw", 31, "$3,410", "-12%" ], [ "Beeswax candle", 118, "$2,242", "+41%" ], [ "Canvas apron", 47, "$1,645", "new" ] ] } }, { "type": "Callout", "props": { "text": "Beeswax candle is up 41% with 96 left in stock: about 6 days at this pace.", "tone": "warn" } } ] } JSON ``` Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report. ## Run it on a schedule Suggested: Mondays at 8:00 (`0 8 * * 1`). From cron, with the agent signed in on that machine: ```bash 0 8 * * 1 claude -p "Run the shopify-top-products skill" # Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run ``` Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/shopify-top-products#schedule Source: https://briefkin.dev/skills/shopify-top-products