The difficult part of a Sidekick AI App Extension is not adding a conversational entry point. The difficult part is making the extension a bounded, explainable, confirmable, and recoverable set of tools. In this post, “development” means designing the tool declarations exposed through the Sidekick app-extension surface, documenting the data and permissions each tool needs, deciding when a merchant must confirm, and preparing explicit behavior for denied permissions, inconsistent data, and uncertain write results.
This article is intentionally narrow. It covers Sidekick App Extension tool declarations, data and permission boundaries, user confirmation, error handling, testing, and rollback. It is not a Storefront MCP tutorial, not a guide to ordinary merchant use of Magic or Sidekick, and not a claim that a merchant can manage every store object through Sidekick. The governing constraint from the official documentation is important: what an extension can do depends on its declared extension surface, its permissions, and current availability. Do not assume that every Sidekick installation exposes the same tools.
1. Define the single intent before writing code
1.1 The engineering outcome this post is designed to produce
The useful deliverable is a tool contract plus a permission matrix, a confirmation matrix, an error-and-rollback plan, and a test specification. It is not a blanket authorization for an AI system to call store APIs. It is also not a promise of automatic correctness. Every proposed capability should answer five questions: why does the tool exist, what does it read, can it write, when must the user confirm, and where does the flow return when something fails?
1.2 Three areas deliberately outside the scope
First, this post does not design Storefront MCP, a headless storefront, or a generic endpoint. Second, ordinary merchant workflows in Sidekick or Magic are not implementation evidence for an app extension. Third, it does not infer that a particular plan, region, account, or installation has a particular tool. Time-sensitive facts are marked checked on 2026-08-30 and must be rechecked before integration.
2. Extension summary: build a path with gates
2.1 The smallest safe path from request to result
A practical path is: understand the request, select a declared tool, check data and permission, show a preview, request confirmation, execute or generate a draft, present the result, and provide a human handoff or rollback route. A generated reply is still AI output and must be reviewed by a merchant or editor. When a request touches real products, orders, inventory, payments, returns, customer data, or store policy, current store data and policy take priority over model memory, a template, or an inference.
2.2 Evidence required at each gate
The table below is an extension summary and implementation proposal. It does not assert that Shopify provides an API or fixed interface with any of these exact names.
| Path stage | What the extension should declare or show | Merchant/editor control | Stop evidence when it fails |
|---|---|---|---|
| Request understanding | Intent, target object, and whether sensitive data is needed | Edit the target or cancel | Ambiguous target; no tool call |
| Tool selection | Tool identifier, purpose, and read/write mode | See the tool about to be called | No declared tool; hand off for verification |
| Data check | Source, time/version cue, and missing fields | Decide whether to supply more context | Missing or stale data; do not guess |
| Preview | Objects to be read or changed and the proposed result | Confirm or reject | Incomplete preview; no write |
| Execute or draft | Result, warnings, status, and error reason | Review, retry, or roll back | Success cannot be proved; treat as incomplete |
| Handoff | Human route and a concise request/tool summary | Verify in the admin or approved workflow | Real state cannot be located; stop automation |
2.3 How to state the capability boundary publicly
Product copy, help text, and acceptance notes should say: “This extension exposes only tools that are declared and currently available; actual capability depends on the extension surface, permissions, and current availability.” Avoid claims such as “once Sidekick is installed, it can manage every order” or “all stores get the same tools.” Accurate boundary language is also the foundation of a usable fallback.
3. Tool declarations: write the contract before the call logic
3.1 Nine fields that every tool should make explicit
Each tool needs a stable internal identifier and a human-readable name. It should also declare its purpose, inputs, outputs, data category, read/write mode, permission basis, confirmation level, failure behavior, and a “must not do” rule. The last field prevents the model from pushing adjacent tasks into one broad, ambiguous tool.
Inputs should not be just one natural-language sentence. They should identify the target object, scope, optional filters, and the response to missing fields. Outputs should not be just generated prose. They should include a source summary, completeness state, whether human confirmation is needed, and an object reference that a person can verify. The exact field shape and invocation method depend on the current extension surface and the application implementation; this post does not invent a platform schema.
3.2 Classify tools by side effect, not by how many tools you can display
The names below are proposed internal design names, not Shopify built-in tool names. They illustrate governance boundaries.
| Design tier | Proposed tool name | Allowed behavior | Default confirmation | Explicitly forbidden |
|---|---|---|---|---|
| L0 context | context.inspect | Read context already supplied by the user or explicitly visible to the extension | No separate confirmation when there is no side effect, but show the source | Guess products, policies, or order facts that were not supplied |
| L1 read-only check | record.lookup | Read an approved object and scope needed for the current request | Required before sensitive order, customer, payment, or return data | Mutate a record under the label of a lookup |
| L2 draft | response.draft | Produce a reply, checklist, or action plan from verified context | Merchant/editor review; never represent it as executed | Turn a draft into a completed-action claim |
| L3 write | change.apply | Apply one explicit change only when current capability, permissions, and business rules allow it | Preview and explicit confirmation every time | Default-on writes, widened batches, or silent retries |
3.3 A safer declaration example
The following YAML is an internal governance template. permission_ref, the actual surface, input/output fields, and the invocation method must be mapped to the current official documentation and approved application configuration during implementation. They are not claims about platform permission-key names.
``yaml tool_id: record.lookup display_name: Read a specified record summary purpose: Read only the merchant-approved scope needed for the current request mode: read_only data_scope: merchant-approved-context-only permission_ref: map-to-current-approved-permission confirmation: required-before-sensitive-read side_effects: none on_missing_or_stale: stop-and-ask-merchant-to-verify on_error: show-reason-and-provide-admin-handoff ``
The deliberately unresolved permission reference is safer than inventing a fixed scope. During code review, the team should attach the real configuration, source, minimum scope, and revocation procedure. If the current extension surface does not support the read, leave the tool disabled; do not compensate with a broader permission.
4. Permissions and data: separate the sensitive layers
4.1 Priority rule for real store data
AI should answer only from context that has been obtained and can be checked. Real product, order, inventory, payment, return, customer, and store-policy data take priority over model memory, examples, or guesses. When the required data is unavailable, the correct result is “this cannot be verified; check the admin,” not a complete-looking answer assembled from assumptions.
4.2 Write the permission matrix at object level
The matrix below is what must be filled with the actual approved configuration before integration. “Approved minimum permission” is intentionally a category here, so the article does not create an unverified platform identifier.
| Data or action | Default treatment | Minimum-permission rule | User confirmation | Fallback |
|---|---|---|---|---|
| Ordinary context supplied by the user | Use only the current request | Add no new read | Usually no side-effect confirmation | Ask for missing fields |
| Product information | Read-only, limited to the requested product or scope | Allow only the read needed for this task | Depends on data sensitivity and current extension ability | Link to the admin or ask an editor to check |
| Inventory, orders, returns, payments | Do not guess or assume access | Request the approved minimum read one category at a time | Explain the object and purpose before reading | Stop the automated answer and hand off |
| Customer data | Highly sensitive; exclude by default | Limit objects, fields, and retention | Clear confirmation; show a redacted view where possible | Do not read or route to a human |
| Store policy | Use the current store policy source | Read only the current effective source | Preview and confirm before any change | Show the version conflict; do not act |
| A write or external action | Off by default | Expose only one auditable action | Explicit confirmation for each scope and attempt | Treat as not executed; verify real state |
4.3 Treat a permission change as a release event
Adding a data category, widening a query, or converting a draft into a write changes the risk boundary. It should not be treated as a small prompt or configuration tweak. The change record should state the new purpose, minimum scope, visible user notice, confirmation text, failure fallback, and test cases. If the request for a permission cannot be explained as necessary for the current tool to complete the current task, it should not be merged.
5. User confirmation: make consent an understandable action
5.1 Three confirmation levels
Use three governance levels: context reading with no side effect, sensitive-data reading, and a write or external action. For the first, show the source directly. For the second, explain the object, fields, purpose, and what happens if information is missing before reading. For the third, show the proposed change, scope, expected result, and what the user should do if the final status is uncertain.
5.2 Confirmation matrix and reusable language
| Situation | What the user should see before confirming | Recommended button meaning | Behavior after rejection |
|---|---|---|---|
| Read ordinary context | Which supplied content will be used | Review suggestion | Generate only from the existing context |
| Read an order/customer or other sensitive object | Object, fields, purpose, and retention/handling note | Allow this read | Do not call the tool; provide human verification |
| Generate a draft | Draft status, evidence, and unknown items | Generate draft for review | Explain what is missing; do not imply completion |
| Write one object | Before/after state, object, scope, and irreversibility risk | Confirm and apply | Keep the original state |
| Batch or external action | Count, filter, total impact, and failure behavior | Review and apply | Narrow the scope or hand off; do not batch by default |
5.3 Confirmation is not a disclaimer
“AI may be wrong; use at your own risk” does not replace confirmation design. A useful confirmation tells the user what will be read, whether state will change, whether the evidence is complete, and what happens if they decline. Even after confirmation, the extension cannot promise real-time accuracy, security, or successful execution. The result still has to be checked against the real store state and current store policy.
6. Safety policy: prevent an error from becoming a larger action
6.1 Every AI output needs merchant or editor review
Replies, classifications, action plans, and field suggestions can all be wrong. The UI should separate “verified fact,” “model suggestion,” and “missing or conflicting information.” When the extension cannot verify a policy version, order state, inventory count, or payment/return condition, it should label the item unknown and route the user to the admin. A longer prompt is not a substitute for missing data.
6.2 Logs should prove what happened, not collect everything
Useful audit entries can include a request identifier, tool identifier, read/write mode, a summary of the data scope, confirmation result, returned status, error category, and handoff time. Do not retain complete customer content, payment details, or unnecessary order fields merely because logging is convenient. The display layer can use a redacted summary; approved people and workflows can inspect the real record when verification is necessary.
6.3 Stop prompt wording from widening a tool
Tool descriptions should reject implicit expansion across objects, stores, and purposes. If a user says, “While you are there, process every customer,” the extension should split that into a new task that requires a new authorization and confirmation. It must not turn that sentence into an expanded filter for a single-object tool. Tool output also cannot become authorization for the next write automatically.
7. Error handling: make failure visible, explainable, and recoverable
7.1 Four errors that deserve distinct behavior
| Error class | User-facing explanation | Extension behavior | Human fallback |
|---|---|---|---|
| Capability unavailable | This installation or extension surface does not provide the tool | Do not substitute an unauthorized tool | Complete the task through an approved admin path |
| Permission denied or confirmation rejected | The required approval was not granted for this attempt | Do not read or write | Narrow the scope or hand off |
| Missing, stale, or conflicting data | The result cannot represent the current store state | Mark unknown; never guess | Check the product, order, or policy in the admin |
| Uncertain execution or failed write | Completion cannot be proved | Stop retrying; keep status unconfirmed | Verify the object, then decide on compensation |
7.2 A safe read-only example
Suppose a merchant asks, “Can this order be handled under the store’s return policy?” The safe path is not to answer “yes” immediately. The extension should recognize that the request needs two sources: the order facts and the current policy. If either the permission or the data is unavailable, it should say that the order or policy cannot be verified and direct the merchant to the admin, without inventing a status. If both can be read, the output should separate order facts, policy version, unknown items, and suggested next steps, then produce a draft for review rather than automatically promising a refund or return.
7.3 No silent retry or silent downgrade
A permission error must not switch automatically to a broader permission. A failed write must not be replayed repeatedly. A data conflict must not be hidden with an old cache. Before any retry, answer three questions: Is this still the same object? Is it still within the original confirmation? Could it create a duplicate side effect? If any answer is unclear, stop and hand off. Time-sensitive facts are recorded as checked on 2026-08-30; integration-time rechecking is still required.
8. Concrete failure and rollback drills
8.1 Drill A: return to human verification after denied permission
Scenario: the merchant asks the extension to read an order and assess return handling, but the current configuration does not approve the required order read. The expected sequence is:
- The router classifies the request as a sensitive read and stops at the permission check; no order content is sent.
- The UI explains that the approved permission needed for this order read was not granted for the current configuration or attempt. It does not display a guessed order state.
- The extension offers two safe routes: the merchant verifies the order in the admin and supplies the necessary facts, or the request goes directly to the human workflow.
- If the merchant declines or no approved route is available, record
not_run, notsuccessand notfailed-after-write. - The tester verifies that no order data leaked, no return or refund action occurred, and no broader permission was requested just to continue the conversation.
The rollback boundary is human verification, not an automatic request for elevated access. Any later read is a new request with a new confirmation.
8.2 Drill B: order facts conflict with the policy version
Scenario: a read-only result contains order facts, but the policy source version does not match the policy currently visible in the store. Treat this as unresolved. Freeze any automatic action, show the two sources and the conflicting fields, and create an editor-only verification checklist. The editor must confirm the current store policy and order facts before deciding whether to continue. The extension must not choose the source that merely looks newer, and it must not rewrite a suggestion as a policy conclusion.
Acceptance evidence includes visible conflict fields, a traceable policy version, no write, and a complete handoff summary. Without human confirmation, the final state remains needs_review.
8.3 Drill C: a confirmed write returns an uncertain status
Scenario: the user confirmed one change, but the extension or network returns an unclear result. Do not call change.apply again immediately. Preserve the confirmation scope and object reference, show “execution status requires verification,” and ask a person to check the real store state. If the state did not change, the user can review and initiate a new attempt. If it did change, close the current flow with the actual result.
Rollback does not mean inventing a reverse mutation. When reversibility, object scope, or real-state evidence is unclear, the rollback boundary is to stop automation, verify the real state, and let an authorized person choose any compensating step. A test specification is a plan; it must not be written as proof that recovery already happened.
9. Development testing and integration recheck
9.1 Test-environment boundary
Run tests in an isolated development store or equivalent non-production environment, using dedicated test records and fictional customer content. Real customer data cannot be used as proof of safety. Test the declared surface, permission interception, confirmation order, error presentation, draft labeling, and human fallback. A test environment can validate the flow, but it does not prove production availability. Current tools, extension surface, account conditions, and other time-sensitive facts must be rechecked before integration.
9.2 The test matrix is an acceptance plan, not an execution report
| ID | Precondition | Action | Expected result | Fallback on failure |
|---|---|---|---|---|
| T01 | Complete ordinary context | Request a suggestion | Evidence and draft label are visible; no write | Stop at draft |
| T02 | Sensitive read is not approved | Request order or customer data | Permission error; no read | Human handoff |
| T03 | User rejects confirmation | Reject before sensitive read | Tool is not called; state is unchanged | End current flow |
| T04 | Required field is missing | Request a policy-related answer | Unknown is shown; verification is requested | needs_review |
| T05 | Two sources conflict | Supply order and policy versions | Conflict is shown; no automatic decision | Freeze writes |
| T06 | Confirmed write times out | Simulate uncertain execution | No replay; verify real state | Human verification |
| T07 | Batch scope is too broad | Submit a cross-object request | Split and reconfirm; no default batch | Narrow scope |
9.3 Minimum contents of a test record
Record the version, environment, tool declaration, permission configuration, confirmation text or screenshot, data category, expected status, actual status, and fallback result. Distinguish pass, fail, blocked, and not executed. A test that was not run cannot be marked passed.
10. Release, monitoring, and rollback boundary
10.1 Release gates
Before merge, check that every tool is separately declared; sensitive data uses an approved minimum permission; writes are off by default; confirmation copy states scope; errors can reach a human; drafts are clearly drafts; real data and policy take priority; and official-source availability has been rechecked. If any gate is missing, keep the extension in development or test status.
10.2 Rollback-boundary table
| Change or incident | Can be automatically contained | Requires human judgment | Immediate action |
|---|---|---|---|
| Wrong label or UI copy | Disable the tool entry and correct the copy | Whether previously shown content needs notice | Mark the version and pause the entry |
| Read-only scope was too broad | Disable the tool and remove unnecessary read configuration | Handling or notification for data already read | Stop calls; retain an audit summary |
| A draft was mistaken for completion | Remove the draft from the active view | Whether anyone acted on it externally | Mark as not executed and give it to an editor |
| Write status is uncertain | Stop retries | Real state, compensation, or reverse action | Verify the object manually |
| Permission or extension surface changed | Disable the affected tool | Whether to request and retest it again | Roll back the version or disable |
Rollback is not a promise that every action is reversible. Without a known reverse action, object scope, and real-state evidence, automation must stop in a safe state. The final decision about production data, orders, payments, returns, customer information, and store policy belongs to an authorized merchant or editor.
10.3 Recheck and documented-fact record
Before integration, recheck the official Sidekick App Extension documentation, AI tools guidance, best-practices guidance, and Sidekick help page. Confirm the current extension surface, permission requirements, confirmation behavior, and availability. These time-sensitive facts were checked on 2026-08-30; do not turn that timestamp into a permanent guarantee.
11. Implementation checklist for code review
11.1 Before coding
Write the single intent and exclusions. List each tool’s read/write mode, data category, inputs, outputs, refusal conditions, and human handoff. Confirm the current extension surface from the official documentation. Keep permission keys, versions, and environment as explicit configuration rather than hiding them in prompt text.
11.2 Before opening review
Walk through ordinary context, a denied sensitive read, an order/policy conflict, draft confusion, and an uncertain write status. A reviewer should be able to tell from the audit record whether a tool was called, whether the user confirmed, what scope was used, and whether the final state was successful, not executed, or awaiting verification. When a result cannot be proved, the UI must preserve uncertainty instead of increasing its tone of certainty.
11.3 Before integration
Run the necessary cases from the test plan in an isolated environment, recheck the official sources and current availability, and prepare a switch for disabling affected tools plus human fallback copy. Implementation notes should describe this as a bounded app extension. They should not promise that every Sidekick installation has the same tools, or that AI output, real-time state, or security outcomes are automatically correct.
Frequently asked questions
12.1 Is this a Storefront MCP tutorial?
No. The subject here is Sidekick App Extension tool declaration, permissions, confirmation, error handling, and test rollback. Storefront MCP, headless storefronts, and other entry points are outside this post’s implementation scope and cannot be used as evidence for the extension surface.
12.2 Can an extension read every order and customer by default?
No. Order and customer data should be limited to the current task, covered by an approved minimum permission, and explained before a sensitive read. If the current extension surface or permission does not support it, stop the read and hand off for verification. The model’s possible knowledge is not a reason to fill in a missing fact.
12.3 Does generating a draft mean the operation is complete?
No. A draft, suggestion, and action plan must be labeled for merchant or editor review. Only an explicitly confirmed action with a verifiable execution result, checked against the real store state, can be described as complete. An uncertain result remains unconfirmed.
12.4 Should a failed write be retried automatically?
Not silently, and not by default. First establish whether a side effect occurred, whether the object is still inside the original confirmation scope, and whether a clear reverse action exists. If not, stop and verify the real state with a human. A new attempt requires a new preview and confirmation.
12.5 How can we prove that the extension works on every Sidekick installation?
We should not make that claim. Capability depends on the declared extension surface, permissions, and current availability, so installations need not be identical. Recheck the target environment before integration and record version, permission, tool visibility, and fallback results while retaining a human path.
13. Official sources and time note
13.1 Official sources
The following official sources define the current capability and safety boundaries: Sidekick app extensions, Shopify AI-powered tools, AI best practices, and Sidekick. Time-sensitive facts are marked checked on 2026-08-30; integration requires a recheck and development-store sign-off.
14. Series links and adjacent-topic boundary
14.1 Link only to related governance topics
For related reading, see AI cross-border Shopify implementation, Shopify Magic and Sidekick workflows, and Shopify B2B AI sales assistant. Those links are not evidence for this post’s tool declarations, permissions, or error behavior. The single intent here remains bounded governance for a Sidekick App Extension.