{"_id":"@shopify/shop","_rev":"5-a63555f1f795594682b8d9f609ec854e","name":"@shopify/shop","dist-tags":{"latest":"1.1.1"},"versions":{"0.0.0-stage":{"name":"@shopify/shop","version":"0.0.0-stage","_id":"@shopify/shop@0.0.0-stage","stub":true,"maintainers":[{"name":"shopify-admin","email":"npmjs@shopify.com"}],"dist":{"shasum":"39314528efed61ad777557058532e83aefe3a56f","tarball":"https://registry.npmjs.org/@shopify/shop/-/shop-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-kTmGsYu4kMrkIaWLMwKd9nE4looZbCvplochZsP32T1AqS538Ps2de073rpppRcGZhOPF8B2xsund/N5tl5Lwg==","signatures":[{"sig":"MEUCIGzfAYqiaVQVTdzZwF2WyR01rk6+A3fqevR3cOo+hM1/AiEAyHlyvEJJwGrE9PhPdszdZKb0YOiKQdceJf3P89Zieu0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":335},"_npmUser":{"name":"shopify-admin","email":"npmjs@shopify.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"1.0.2":{"name":"@shopify/shop","version":"1.0.2","license":"MIT","_id":"@shopify/shop@1.0.2","maintainers":[{"name":"jaimie.way","email":"jaimie.way@shopify.com"},{"name":"shopify-admin","email":"npmjs@shopify.com"},{"name":"shopify-dep","email":"npmjs+shopify-dep@shopify.com"},{"name":"mishsmelle","email":"michelle.oconnor@shopify.com"},{"name":"buitammy","email":"tammy.bui@shopify.com"},{"name":"chris.craig","email":"chris.craig@shopify.com"}],"homepage":"https://github.com/Shopify/shop#readme","bugs":{"url":"https://github.com/Shopify/shop/issues"},"bin":{"shop":"bin/shop.mjs"},"dist":{"shasum":"49bf09fd3c9468cdf4b94d88bb7ee572df39246c","tarball":"https://registry.npmjs.org/@shopify/shop/-/shop-1.0.2.tgz","fileCount":25,"integrity":"sha512-hoN1Ix5SXUOA0T6mw0vP4erAi4IfuoMiNplCjgdnIH2zTF2GRzmaanZwLwa2lqp9kWQhAmkEGUdTGcoAuMjvpw==","signatures":[{"sig":"MEYCIQDn6GsuwSc4JyKxKvzybtJ7UaABl9GDZJJ4LTBt4Wx76wIhAJYzknpdYVljRhDu+ZWocCqtd+lAwVdStruQoiaDdAYt","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIAxDKkLjlJ427wtGC5eFg0F9fvt1D9D1/PUT/1QAWr+JAiEA7pH8xdrR0UEdtHaRVDvoNk6EQNwHtIO01oNs+x32CMQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@shopify%2fshop@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":2032384},"type":"module","engines":{"node":">=22.21.0 <23 || >=24.5.0 <25"},"gitHead":"df215e9bcdd6b7655e24314f781369ec1eb7aa78","scripts":{"postinstall":"node scripts/postinstall.mjs"},"_npmUser":{"name":"shopify-admin","email":"npmjs@shopify.com"},"repository":{"url":"git+https://github.com/Shopify/shop.git","type":"git"},"_npmVersion":"11.19.0","description":"Shop for agents: product discovery, checkout, and Shop order tracking across millions of stores","directories":{},"_nodeVersion":"24.21.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/shop_1.0.2_1791401123657_0.6022900970130074","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@shopify/shop","version":"1.0.3","license":"MIT","_id":"@shopify/shop@1.0.3","maintainers":[{"name":"jaimie.way","email":"jaimie.way@shopify.com"},{"name":"shopify-admin","email":"npmjs@shopify.com"},{"name":"shopify-dep","email":"npmjs+shopify-dep@shopify.com"},{"name":"mishsmelle","email":"michelle.oconnor@shopify.com"},{"name":"buitammy","email":"tammy.bui@shopify.com"},{"name":"chris.craig","email":"chris.craig@shopify.com"}],"homepage":"https://github.com/Shopify/shop#readme","bugs":{"url":"https://github.com/Shopify/shop/issues"},"bin":{"shop":"bin/shop.mjs"},"dist":{"shasum":"b2ba815fe1f90f9ede4e046ac3a4e418ce1b5d66","tarball":"https://registry.npmjs.org/@shopify/shop/-/shop-1.0.3.tgz","fileCount":25,"integrity":"sha512-CL3WHRqBIKD8NpiZx5O6oEgsfXC0sM3usohy0fruXC3YITspHZ3wBq/WdAwW6QzVNxCsKMgPk0+IagVwrSM/gg==","signatures":[{"sig":"MEQCIDt1PdIjisRx9tDpU13F+mH0bVkEdE+AUsdQPmxJyqbFAiBMcRYE+qKhOxOl2yTgCDFAEYfJgBNJxCYPWGqaWMaWeQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIAa/0ErBDBrSNDWXrDRzGTXI89zbbyhHlu5Ge1ybSri6AiB0VkGW06hXBQdJzPtcBsZ/B3d8zOGIRAQ5uWSWeM3pTw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@shopify%2fshop@1.0.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":2038799},"type":"module","engines":{"node":">=22.21.0 <23 || >=24.5.0 <25"},"gitHead":"d1e8c7c4b3cba4ece59b01d7505e2793a2aef732","_npmUser":{"name":"shopify-admin","email":"npmjs@shopify.com"},"repository":{"url":"git+https://github.com/Shopify/shop.git","type":"git"},"_npmVersion":"11.19.0","description":"Shop for agents: product discovery, checkout, and Shop order tracking across millions of stores","directories":{},"_nodeVersion":"24.21.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/shop_1.0.3_1791422430665_0.5605980925246785","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@shopify/shop","version":"1.1.0","license":"MIT","_id":"@shopify/shop@1.1.0","maintainers":[{"name":"jaimie.way","email":"jaimie.way@shopify.com"},{"name":"shopify-admin","email":"npmjs@shopify.com"},{"name":"shopify-dep","email":"npmjs+shopify-dep@shopify.com"},{"name":"mishsmelle","email":"michelle.oconnor@shopify.com"},{"name":"buitammy","email":"tammy.bui@shopify.com"},{"name":"chris.craig","email":"chris.craig@shopify.com"}],"homepage":"https://github.com/Shopify/shop#readme","bugs":{"url":"https://github.com/Shopify/shop/issues"},"bin":{"shop":"bin/shop.mjs"},"dist":{"shasum":"d242c796ebd13defbeec263c7f8e744b7f8d9952","tarball":"https://registry.npmjs.org/@shopify/shop/-/shop-1.1.0.tgz","fileCount":25,"integrity":"sha512-tWFsBAWQFWLUdvRiuYzFCrF9leAaIyoHRuZRMbUMH451dw6la1/SkoBFMAMWvjYtIxxbubXFSetVUn1+qRfYUA==","signatures":[{"sig":"MEYCIQCF32mZU4gfw6WBCZhGr9rVDfh9ayMFcgNfrUiRP/k2QwIhAM0zRhKe2NBrTRZ8prFEM1iwmTTzXXE2p8GwwgyVVGh7","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIC6ZSV22z+RgOkuiLwAaZlM9fsPe5y9HjHQF46eFpBVIAiBS4LHnLPpjBtWzG5xWAOpDCxR9Th/wGHuzG8sCVlGHsA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@shopify%2fshop@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":2042691},"type":"module","engines":{"node":">=22.21.0 <23 || >=24.5.0 <25"},"gitHead":"a77b67ef470847439bb47996cab27e50bb794cb8","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"4c77cdcd-6cfc-4d50-9d8b-aeff94c5ab17"}},"repository":{"url":"git+https://github.com/Shopify/shop.git","type":"git"},"_npmVersion":"11.19.0","description":"Shop for agents: product discovery, checkout, and Shop order tracking across millions of stores","directories":{},"_nodeVersion":"24.21.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/shop_1.1.0_1791914834714_0.7517911407382256","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"_id":"@shopify/shop@1.1.1","bin":{"shop":"bin/shop.mjs"},"bugs":{"url":"https://github.com/Shopify/shop/issues"},"dist":{"shasum":"3c16037cad3a84ec10c479764eb6d76c4a782c40","tarball":"https://registry.npmjs.org/@shopify/shop/-/shop-1.1.1.tgz","fileCount":25,"integrity":"sha512-J7D9mChc0U4LPyQlpI4s0bEdnZ3xVZgTYmgPS2D4rsjJAvEFziyQXf5sz0PsVZmjucDEOJNvsSy4q4YdoFAxEA==","signatures":[{"sig":"MEUCIGOA2/CxTKbvj9w9Rwj/g46ihO+K22i/pVdEEyszDk8NAiEA1HkZHMwWjGbDR2nKbOkHZ7p8jmZDM2G/s2X+yBNGSbQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFqg1AhBgJa+RFcFUQSaBSSk7M4HX7PWasH0vL4y+8VUAiEAlE8CSJObsvOIiqHYji8tnk5bzJT3z5KhjTVqrE+T18c="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@shopify%2fshop@1.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":2049940},"name":"@shopify/shop","type":"module","engines":{"node":">=22.21.0 <23 || >=24.5.0"},"gitHead":"bf9880ef08c00f5d911701315d3fc323faedc3c4","license":"MIT","version":"1.1.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"4c77cdcd-6cfc-4d50-9d8b-aeff94c5ab17"}},"homepage":"https://github.com/Shopify/shop#readme","repository":{"url":"git+https://github.com/Shopify/shop.git","type":"git"},"_npmVersion":"11.19.0","description":"Shop for agents: product discovery, checkout, and Shop order tracking across millions of stores","directories":{},"maintainers":[{"name":"jaimie.way","email":"jaimie.way@shopify.com"},{"name":"shopify-admin","email":"npmjs@shopify.com"},{"name":"shopify-dep","email":"npmjs+shopify-dep@shopify.com"},{"name":"mishsmelle","email":"michelle.oconnor@shopify.com"},{"name":"buitammy","email":"tammy.bui@shopify.com"},{"name":"chris.craig","email":"chris.craig@shopify.com"}],"_nodeVersion":"24.21.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/shop_1.1.1_1791985361733_0.7453368070294151"}}},"time":{"created":"2026-10-07T19:21:03.668Z","modified":"2026-10-14T13:42:42.398Z","0.0.0-stage":"2026-10-07T19:21:03.668Z","1.0.2":"2026-10-07T19:25:23.777Z","1.0.3":"2026-10-08T01:20:30.781Z","1.1.0":"2026-10-13T18:07:14.822Z","1.1.1":"2026-10-14T13:42:41.928Z"},"bugs":{"url":"https://github.com/Shopify/shop/issues"},"license":"MIT","homepage":"https://github.com/Shopify/shop#readme","repository":{"url":"git+https://github.com/Shopify/shop.git","type":"git"},"description":"Shop for agents: product discovery, checkout, and Shop order tracking across millions of stores","maintainers":[{"name":"jaimie.way","email":"jaimie.way@shopify.com"},{"name":"shopify-admin","email":"npmjs@shopify.com"},{"name":"shopify-dep","email":"npmjs+shopify-dep@shopify.com"},{"name":"mishsmelle","email":"michelle.oconnor@shopify.com"},{"name":"buitammy","email":"tammy.bui@shopify.com"},{"name":"chris.craig","email":"chris.craig@shopify.com"}],"readme":"# shop\n\n`shop` lets agents search millions of stores, build carts, check out and pay with the shopper's Shop account, and track orders. When a store has no agent checkout, the shopper can approve a purchase on Shop and the agent gets a one-time credential to pay at the site's own checkout.\n\n## Contents\n\n- [Install](#install)\n- [Search for products](#search-for-products)\n- [Sign in for personalization and accelerated checkout](#sign-in-for-personalization-and-accelerated-checkout)\n- [Read the shopper's addresses and payment methods](#read-the-shoppers-addresses-and-payment-methods)\n- [Create a pre-filled checkout](#create-a-pre-filled-checkout)\n- [Complete the checkout](#complete-the-checkout)\n- [Track the order](#track-the-order)\n- [Approve a browser purchase](#approve-a-browser-purchase)\n- [Direct MCP integration](#direct-mcp-integration)\n- [Reference](#reference)\n\n## Install\n\n```sh\nnpm install --global @shopify/shop@latest\nshop skill --install\n```\n\nInstalls the `shop` command, then teaches your agent when and how to use it. Then ask your agent:\n\n> Find three rain jackets under US$100 that ship to the US.\n\nA full purchase, from search to tracking, takes five commands:\n\n```sh\nshop search \"trail running shoes\" --ships-to US --limit 3\nshop cart create --shop example-store.com --variant gid://shopify/ProductVariant/1001 --quantity 1\nshop checkout create --shop example-store.com --cart gid://shopify/Cart/…\nshop checkout complete gid://shopify/Checkout/… --shop example-store.com --instrument '…'\nshop order search \"trail running shoes\"\n```\n\n## Search for products\n\n```sh\nshop search \"trail running shoes\" --ships-to US --currency USD --limit 3\n```\n\n<details>\n<summary>Example output</summary>\n\n```jsonc\n{\n  \"ok\": true, \"v\": 1,\n  \"data\": {\n    \"products\": [\n      {\n        \"id\": \"gid://shopify/p/7Qk2mN9pR4sT6vW8xY0zA1\",\n        \"title\": \"Ridgeline Trail Runner\",\n        \"description\": { \"plain\": \"Lightweight trail running shoes with a grippy outsole…\" },\n        \"variants\": [{\n          \"id\": \"gid://shopify/ProductVariant/1001\",\n          \"price\": { \"amount\": 14500, \"currency\": \"USD\" },\n          \"availability\": { \"available\": true },\n          \"options\": [{ \"name\": \"Size\", \"label\": \"10\" }, { \"name\": \"Color\", \"label\": \"Slate\" }],\n          \"rating\": { \"value\": 4.7, \"scale_max\": 5, \"count\": 212 },\n          \"seller\": { \"name\": \"Example Store\", \"url\": \"https://example-store.com\", \"domain\": \"example-store.myshopify.com\" },\n          \"checkout_url\": \"https://example-store.com/cart/1001:1?…&payment=shop_pay\"\n        }]\n      },\n      // …two more products\n    ],\n    \"pagination\": { \"has_next_page\": true, \"total_count\": 1180 },\n    \"next\": [\n      \"A featured variant may already answer the user's needs; use get_product only for other options or a concrete missing fact…\",\n      // …\n    ]\n  }\n}\n```\n\n</details>\n\nPrices are integers in the currency's minor units, so `14500` is US$145.00.\n\nBeyond a text query, a search can be shaped three ways:\n\n- Filters such as `--ships-to`, `--price-max` and `--size` are hard constraints.\n- `--intent` describes what the shopper needs and steers the ranking.\n- `--like-image` and `--like-id` find products similar to an image or to another product.\n\n```sh\nshop search --like-image ./jacket.jpg --ships-to US\nshop search --like-id gid://shopify/p/7Qk2mN9pR4sT6vW8xY0zA1 --limit 3\nshop search \"trail shoes\" --intent \"wide feet, wet Pacific Northwest trails\" --price-max 20000 --size 11\n```\n\nEvery variant also has a `checkout_url`, a buy-now link to the merchant's checkout. A shopper signed in to Shop sees a one-tap review screen there. They can approve the purchase as it is, or change the delivery option, payment method, discounts, and more first.\n\n## Sign in for personalization and accelerated checkout\n\nSign-in is optional: search, carts, and checkouts work without it. Signing in to Shop adds:\n\n- Search results ranked using the shopper's own history.\n- Carts and checkouts that arrive with the shopper's saved address and payment preference filled in.\n- The account, checkout completion, order, and spend-request commands in the sections below.\n\n```sh\nshop account login --device-name \"My Awesome Agent\"\n```\n\n<details>\n<summary>Example output</summary>\n\n```json\n{\n  \"ok\": true, \"v\": 1,\n  \"data\": {\n    \"signed_in\": false,\n    \"pending\": {\n      \"verification_uri\": \"https://accounts.shop.app/device\",\n      \"verification_uri_complete\": \"https://accounts.shop.app/device?user_code=…\",\n      \"user_code\": \"…\",\n      \"expires_at\": \"…\",\n      \"interval\": 5\n    }\n  }\n}\n```\n\n</details>\n\nSigning in takes two runs of the same command:\n\n1. With `--wait 0`, it returns a link and code right away. The agent shows them to the shopper.\n2. With `--wait 90`, it waits up to 90 seconds for the shopper to approve on Shop and returns `signed_in: true` as soon as they do. If they haven't approved yet, it returns `signed_in: false` and the agent can run it again.\n\n`--device-name` is the name Shop's approval page shows for the agent. Once the shopper approves, the CLI attaches the credential to every request.\n\n## Read the shopper's addresses and payment methods\n\n```sh\nshop account\n```\n\n<details>\n<summary>Example output</summary>\n\n```jsonc\n{\n  \"ok\": true, \"v\": 1,\n  \"data\": {\n    \"signed_in\": true,\n    \"buyer\": { \"email\": \"ada@example.com\" },\n    \"addresses\": [{\n      \"id\": \"address-a\", \"type\": \"shipping_address\",\n      \"first_name\": \"Ada\", \"last_name\": \"Lovelace\",\n      \"street_address\": \"1 Example Way\", \"address_locality\": \"London\", \"address_country\": \"GB\", \"postal_code\": \"SW1A 1AA\"\n    }],\n    \"preferred_address_id\": \"address-a\",\n    \"selectable_instruments\": [{\n      \"id\": \"3f1e2d4c-5b6a-4789-8abc-def012345678\",\n      \"type\": \"shop_pay\",\n      \"display\": { \"funding_instrument\": { \"type\": \"card\", \"brand\": \"visa\", \"last_digits\": \"4242\" } }\n    }],\n    \"preferred_instrument_id\": \"3f1e2d4c-5b6a-4789-8abc-def012345678\",\n    \"payment\": { \"instruments\": [{ \"type\": \"shop_pay\", \"display\": { \"limit\": 10000, \"remaining_amount\": 8000, \"renewal_type\": \"monthly\" } }] }\n    // …links, messages\n  }\n}\n```\n\n</details>\n\nThe response has the shopper's saved details, each with an `id`:\n\n- `addresses`: saved delivery addresses. `preferred_address_id` is the one the shopper prefers.\n- `selectable_instruments`: saved Shop Pay cards. `preferred_instrument_id` is the one the shopper prefers.\n- `payment.instruments[].display`: a budget, if the shopper set one on shop.com and delegated it to agents. It shows the limit, how much remains, and how often it renews. Within that limit, the agent can complete purchases without asking for approval each time.\n\nWhen a checkout needs a destination or a payment instrument, the agent passes one of these `id`s. It never types an address or asks for a card number.\n\n## Create a pre-filled checkout\n\nCreate a cart, then turn it into a checkout:\n\n```sh\nshop cart create --shop example-store.com --variant gid://shopify/ProductVariant/1001 --quantity 1\nshop checkout create --shop example-store.com --cart gid://shopify/Cart/…   # the response below\n```\n\n<details>\n<summary>Example output</summary>\n\n```jsonc\n{\n  \"ok\": true, \"v\": 1,\n  \"data\": {\n    \"id\": \"gid://shopify/Checkout/…\",\n    \"status\": \"ready_for_complete\",\n    \"buyer\": { \"email\": \"ada@example.com\", \"phone_number\": \"+1555…\" },\n    \"line_items\": [{ \"id\": \"line-a\", \"item\": { \"id\": \"gid://shopify/ProductVariant/1001\", \"title\": \"Ridgeline Trail Runner — Size 10, Slate\", \"price\": 14500 }, \"quantity\": 1 }],\n    \"fulfillment\": { \"methods\": [{ \"type\": \"shipping\", \"selected_destination_id\": \"address-a\", \"groups\": [{ \"selected_option_id\": \"standard\", \"options\": [ /* … */ ] }] }] },\n    \"totals\": [{ \"type\": \"subtotal\", \"amount\": 14500 }, { \"type\": \"fulfillment\", \"amount\": 0 }, { \"type\": \"tax\", \"amount\": 1290 }, { \"type\": \"total\", \"amount\": 15790 }],\n    \"payment\": { \"instruments\": [{ \"id\": \"instrument-a\", \"handler_id\": \"shop_pay\", \"type\": \"shop_pay\", \"display\": { \"funding_instrument\": { \"brand\": \"visa\", \"last_digits\": \"4242\" } } }] },\n    \"continue_url\": \"https://example-store.com/checkouts/…\"\n  }\n}\n```\n\n</details>\n\nThe checkout's `status` says what happens next:\n\n- `ready_for_complete`: nothing is missing. The contact details, delivery address, and Shop Pay card all came from the shopper's account.\n- `requires_escalation`: something is missing. `messages[]` says what, and the shopper finishes at `continue_url`.\n\n`--patch` is the efficient way to change a checkout. You write only the edit, as an RFC 6902 patch, and the CLI:\n\n1. Reads the current checkout.\n2. Applies the patch to that copy.\n3. Sends the merchant the full updated document.\n\nAn edit to a line must first `test` that line's `id`. If the checkout changed after the CLI read it, the edit then fails instead of changing the wrong line:\n\n```sh\nshop checkout update gid://shopify/Checkout/… --shop example-store.com \\\n  --patch '[{\"op\":\"test\",\"path\":\"/line_items/0/id\",\"value\":\"line-a\"},{\"op\":\"replace\",\"path\":\"/line_items/0/quantity\",\"value\":2}]'\n```\n\n## Complete the checkout\n\nPass one of the instruments the checkout offered in `payment.instruments`. The CLI marks it selected and changes nothing else:\n\n```sh\nshop checkout complete gid://shopify/Checkout/… --shop example-store.com \\\n  --instrument '{\"id\":\"instrument-a\",\"handler_id\":\"shop_pay\",\"type\":\"shop_pay\",\"credential\":{\"type\":\"shop_token\"}}'\n```\n\n<details>\n<summary>Example output</summary>\n\n```jsonc\n{\n  \"ok\": true, \"v\": 1,\n  \"data\": {\n    \"status\": \"completed\",\n    \"order\": { \"id\": \"gid://shopify/Order/…\", \"label\": \"#1042\", \"permalink_url\": \"https://example-store.com/…/orders/…\" }\n    // …line items, totals, payment as charged\n  }\n}\n```\n\n</details>\n\n## Track the order\n\n```sh\nshop order search \"trail runner\"\n```\n\n<details>\n<summary>Example output</summary>\n\n```jsonc\n{\n  \"ok\": true, \"v\": 1,\n  \"data\": {\n    \"orders\": [{\n      \"id\": \"…\", \"label\": \"#1042\", \"placed_at\": \"…\",\n      \"seller\": { \"name\": \"Example Store\", \"domain\": \"example-store.com\" },\n      \"line_items\": [{ \"item\": { \"title\": \"Ridgeline Trail Runner — Size 10, Slate\", \"price\": 14500 }, \"quantity\": { \"original\": 1, \"fulfilled\": 1 } }],\n      \"fulfillment\": { \"events\": [{ \"carrier\": \"UPS\", \"tracking_url\": \"https://…\", \"occurred_at\": \"…\" }] },\n      \"permalink_url\": \"https://…\"\n    }],\n    \"shipments\": [ /* standalone shipments Shop tracks without an order */ ]\n    // …\n  }\n}\n```\n\n</details>\n\nThe results cover orders placed through this agent from any store, plus the shopper's other recent and in-progress orders that Shop tracks. Leave out the query to get the most recent orders.\n\n## Approve a browser purchase\n\nSome stores have no agent checkout API (UCP); the agent has to enter a payment credential into the site's checkout form in a browser. A spend request covers that case — it is not a fallback for a Shop checkout that failed or needs the shopper:\n\n1. The agent describes the purchase with `shop spend-request create`.\n2. The shopper reviews and approves it on Shop.\n3. `shop spend-request get` returns a one-time credential that fills the card fields of the site's checkout form, good for up to the `approval_limit` the shopper saw and approved.\n4. The agent pays at the site's checkout and reports the outcome with `shop spend-request complete`.\n\n`--intent` is required: describe the purchase and rationale in the shopper's language (100–500 characters; no links, card details, emails or addresses) — it is what they read on the Shop approval page. In `--arguments` it is `context.intent`. `--instrument-id` names one of the `selectable_instruments` from `shop account`; omit it to use the shopper's preferred card. `--currency` is the code the site's checkout charges in; never convert. `--business-country` is the business's two-letter country when the site states it; omit it rather than guess. Nested values such as line items take JSON, a `@file`, or `-` for stdin:\n\n```sh\nshop spend-request create \\\n  --business-name \"Ridgeline Running\" --business-url https://ridgeline-running.example \\\n  --currency USD --approval-limit 12500 \\\n  --line-item @items.json \\\n  --total '{\"type\":\"total\",\"amount\":12500}' \\\n  --intent \"The trail running shoes you asked me to order this morning from Ridgeline Running, wide fit, in your usual size\"\n```\n\n```jsonc\n// items.json\n{ \"item\": { \"title\": \"Trail running shoe, wide, men's 11\", \"price\": 12500 }, \"quantity\": 1 }\n```\n\n<details>\n<summary>Example output</summary>\n\n```json\n{\n  \"ok\": true, \"v\": 1,\n  \"data\": {\n    \"id\": \"0198e63b-1234-7abc-8def-123456789abc\",\n    \"status\": \"pending\",\n    \"approval_limit\": 12500,\n    \"continue_url\": \"https://accounts.shop.app/…\",\n    \"expires_at\": \"…\"\n  }\n}\n```\n\n</details>\n\nGive the shopper the `continue_url`, then wait for their approval. `--output-file` keeps the credential out of the transcript: the issued instrument is written to a new file only you can read, and stdout carries the status and terms:\n\n```sh\nshop spend-request get 0198e63b-1234-7abc-8def-123456789abc --wait 90 --output-file ./card.json\n```\n\n<details>\n<summary>Example output</summary>\n\n```jsonc\n{\n  \"ok\": true, \"v\": 1,\n  \"data\": {\n    \"status\": \"consumed\",\n    \"credential_output_file\": \"./card.json\"\n    // …terms as approved\n  }\n}\n```\n\n```jsonc\n// card.json\n{\n  \"spend_request_id\": \"0198e63b-1234-7abc-8def-123456789abc\",\n  \"instrument\": {\n    \"type\": \"card\",\n    \"display\": { \"last_digits\": \"…\" },\n    \"credential\": { \"type\": \"pan\", \"number\": \"5556…\", \"expiry_month\": \"…\", \"expiry_year\": \"…\", \"cvv\": \"…\", \"name\": \"Ada Lovelace\" },\n    \"billing_address\": { \"street_address\": \"1 Example Way\", \"address_locality\": \"London\", \"address_country\": \"GB\", \"postal_code\": \"SW1A 1AA\" }\n  }\n}\n```\n\n</details>\n\nThe credential arrives when the status is `consumed`. Hand the file to the program that fills the checkout form; without `--output-file`, the instrument is returned inline instead.\n\nAfter paying at the site's checkout, the agent reports the outcome:\n\n```sh\nshop spend-request complete 0198e63b-1234-7abc-8def-123456789abc \\\n  --status success --order '{\"id\":\"EB-20931\",\"total\":1495,\"currency\":\"USD\"}'\n```\n\n<details>\n<summary>Example output</summary>\n\n```json\n{\n  \"ok\": true, \"v\": 1,\n  \"data\": { \"id\": \"0198e63b-1234-7abc-8def-123456789abc\", \"result\": { \"status\": \"success\", \"recorded_at\": \"…\" } }\n}\n```\n\n</details>\n\nThe response only confirms that Shop recorded the report. It is not proof that the payment went through.\n\n## Direct MCP integration\n\nThe CLI is a client of Shop's MCP server at `https://mcp.shop.com/`. Apart from sign-in, each command above calls one of its tools:\n\n- Most commands send a single `tools/call`. `--patch` reads the checkout before it writes, and `--wait` polls.\n- The CLI adds argument parsing, sign-in, and the JSON envelope.\n\nTo see the requests, or to call a tool by its MCP name:\n\n```sh\nshop checkout create --shop example-store.com --cart gid://shopify/Cart/… --dry-run    # the exact request, unsent\nshop cart get gid://shopify/Cart/… --shop example-store.com --as curl                  # the exact request, as curl\nshop call search_catalog --arguments '{\"catalog\":{\"query\":\"rain jacket\",\"pagination\":{\"limit\":3}}}'   # any tool by MCP name\nshop tools                                                                              # every command, its tool, its schema\n```\n\nTo use the server without the CLI:\n\n- Connect an MCP host to `https://mcp.shop.com/` to access the same tools. Sign-in goes through the host's OAuth flow, against the same Shop account, and the tools behave as they do in the CLI.\n- A host that supports the skills extension ([SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension)) finds the server's skill with `skills/list` on the same connection and reads its files with `resources/read`, so there is nothing to install. This package bundles the same skill.\n- A backend that already holds a Shop token for this resource can hand it to the CLI as `SHOP_ACCESS_TOKEN`; the CLI sends it unchanged, never stores or refreshes it, and a rejected token says whether to mint a fresh one (401) or widen the grant (403). The full contract is in the CLI guide.\n\nInstall the skill from an installed `shop` command:\n\n```sh\nshop skill --install\n```\n\n## Reference\n\n```sh\nshop --help                 # the command tree\nshop search --help          # a command's flags and examples\nshop search --schema        # its complete input schema\nshop tools                  # every command with its MCP tool, usage and schema, as JSON — for agents\nshop skill                  # the bundled agent guidance, as prose\n```\n\nEvery command accepts `--arguments <JSON|@FILE|->` with the complete argument object from `--schema`.\n\n| Exit | Meaning |\n| --- | --- |\n| 0 | ok |\n| 1 | no response from the network |\n| 2 | usage error |\n| 3 | sign-in required |\n| 4 | the merchant or Shop answered with an error |\n\nErrors use the same JSON envelope, and their `next` steps say what to do:\n\n```json\n{\"ok\":false,\"v\":1,\"error\":{\"code\":\"auth_required\",\"message\":\"Not signed in on this device\",\"retryable\":false,\"next\":[\"Run shop account login --wait 0 and show the shopper the verification URL and code\",\"Run shop account login --wait 90 to finish once they approve\",\"Retry this command after signing in\"]}}\n```\n\nRun `shop skill --install` again after upgrading `shop` to replace the installed guidance.\n","readmeFilename":"README.md"}