Shopify Admin API scopes

Scopes are the real perimeter

A Shopify Admin API scope is not a vague setting; it is a string like read_orders or write_customers that Shopify enforces at the HTTP layer. When your AI support tool calls the Admin API, Shopify checks the access token against those strings and rejects anything outside them. That makes scopes the cheapest place to enforce boundaries, cheaper than prompt engineering or post-hoc logs.

I treat scopes as the first line of defense, not a paperwork step. For a typical support AI, the real needs are narrow: read orders to answer “where is my package,” read customers to verify identity, read products to check stock, and maybe write draft orders for replacements. Anything beyond that (write_products, write_themes, read_all_orders) should earn a written justification.

The Shopify Admin API scopes docs list every permission, and I use that page as the checklist during onboarding. If a vendor cannot tell me which endpoint each scope supports, I do not grant it.

The over-scoping trap

The most common mistake I see is granting write_orders because the AI “might need to cancel orders someday.” That day rarely comes, but the token now has the power to modify live orders through an automated system. Once a scope is granted, it stays granted until someone audits it, and most teams forget. I have cleaned up integrations where the support bot had the same permissions as the head of operations.

The fix is to scope for today’s workflow, not tomorrow’s roadmap. If the AI only looks up tracking numbers, it gets read_orders and nothing else. If it creates replacement draft orders, it gets write_draft_orders, not write_orders. I also separate read and write tokens when possible: a lookup-only bot gets a custom app with read scopes, while a separate automation handles writes under stricter controls.

This split limits blast radius if one token leaks or one function goes wrong.

Mapping AI actions to minimum scopes

Before I grant anything, I make a table: AI action on the left, required Shopify scope in the middle, business owner on the right. “Check order status” maps to read_orders. “Verify customer identity” maps to read_customers. “Suggest a replacement product” maps to read_products. “Create a replacement draft order” maps to write_draft_orders. If an action does not have a clear owner, it does not get a scope. This mapping also exposes scope creep.

A vendor will ask for read_all_orders, which reaches across all shop locations and historical data, when read_orders is enough for the last 60 days. I push back every time. The OpenAI function calling guide is useful here because it forces you to define each tool and its parameters; I use that discipline to keep each function tied to one narrow scope. If a function cannot justify its scope, it gets cut.

Auditing tokens and reviewing access

Scopes are only as good as the token that carries them. I schedule a quarterly review of all custom apps and private apps connected to the store, read the scope list, and compare it to the AI’s current capabilities. If a scope has not been used in 90 days, I revoke it and watch for breakage. Most of the time nothing breaks, which tells you how over-scoped the original setup was.

I also rotate API credentials at least once a year, or immediately after a team change, a vendor breach announcement, or any suspicious activity in the Shopify admin event log. Store the token in a secrets manager, never in the AI tool’s front-end config or a shared spreadsheet. Leaked tokens are bad; leaked tokens with write scope on customers and orders are a data incident waiting to happen.

The audit takes an hour; the incident it prevents can take weeks.

Failure modes at both extremes

Too many scopes and a confused AI can cause real damage. I have seen a support bot with write_orders cancel an order because the customer’s message contained the word “cancel” and the function parser was too eager. With read-only scopes, the worst outcome is a wrong answer, not a changed database. That is why I default to read-only unless a write action is explicitly approved and logged. Too few scopes also hurts.

If the bot cannot read draft orders, it will tell a customer “I can’t see that” and create a ticket, which defeats the purpose of containment rate. The goal is not minimalism for its own sake; it is matching each capability to a real, governed action. I test the boundary by running a set of adversarial prompts and watching the API logs.

Any unexpected endpoint call is a scope or function-calling bug that needs fixing before launch.

Building a written scope policy

Every store that runs AI support should have a one-page scope policy. It lists the approved scopes, the AI actions they enable, the owner who approved them, and the date of the next review. I make the policy part of the vendor security questionnaire. If a new feature needs a new scope, it goes through the same approval path, not a quick Slack yes. The policy should also define what is off-limits.

In my shops, support AI never gets write_products, write_themes, read_all_orders, or access to payouts and analytics. Those are operator tools, not support tools. I link the policy to the tool calling spec so engineers know each function must match an approved scope. When the policy is clear, the conversation with vendors changes from “just give it full access” to “prove you need this one string.”