Hosted commerce

AI agent for Shopify (hosted app, OAuth2)

A hosted app using OAuth2, where the adapter holds the Admin API token. One adapter serves both storefront shoppers and back-office merchants — persona is just the user's role and permissions.

Auth method: oauth2 (adapter holds the Shopify Admin API token)

Shopify is a hosted app that authenticates with OAuth2. Your adapter is a small external service that holds the Shopify Admin API token, exchanges and refreshes it, and translates Cambiary's five-method contract into Admin GraphQL/REST calls. You register the host with authMethod "oauth2"; the platform-side contract is otherwise identical to any other adapter.

A storefront-plus-back-office commerce product has two very different personas sharing one host app: a customer who tracks orders and starts returns, and a merchant who manages catalog, issues refunds, and adjusts inventory. Both are served by the same single adapter. The persona is expressed entirely through user.role, permissionRefs, and availableActions in the HostContext — the governance layer then gives each persona different powers with no branching in the platform core.

That means a customer asking "refund me now" simply has no issue_refund permission, so the gateway denies that step and the agent explains it routed the request to support instead. A merchant issuing the same refund gets a controlled_write approval card showing the amount and order before anything executes.

Highlights

One adapter, two personas — customer and merchant

OAuth2: the adapter holds the Admin API token

Refunds and inventory edits gate for human approval

Swapping to self-hosted nopCommerce is an adapter-internal detail

How the integration works

The integration path.

Embed <agentic-panel> in your embedded Shopify app or storefront theme and build a HostContext from the current screen and the signed-in user's role.

Stand up an out-of-process adapter service that holds the Shopify Admin API token and implements the five methods over the Admin GraphQL/REST API.

Map roles to tool-permission strings in getPermissions — customers get read + safe_create; merchants additionally get controlled_write refunds and inventory.

Dispatch executeTool to the Admin API idempotently; refunds and stock edits are controlled_write and pause for approval.

Worked example

Persona is just role + permissions in the HostContext

// Customer (storefront) — read + safe_create only
document.getElementById("shop-agent").config = {
  apiBaseUrl: "https://agent.shop.example.com",
  hostToken: SHOP.customerJwt,
  hostContext: {
    hostApp: "storefront",
    tenantId: SHOP.storeId,
    user: { id: SHOP.customer.id, role: "customer",
            permissionRefs: ["perm:orders.read.own", "perm:returns.create.own"] },
    entity: { type: "order", id: SHOP.order.id, label: "#" + SHOP.order.number },
    availableActions: [
      { id: "track_order",  label: "Track",  riskLevel: "read_only" },
      { id: "start_return", label: "Return", riskLevel: "safe_create" },
    ],
  },
};

// Merchant (back office) — same component, richer permissions + actions
// user.role: "merchant_admin", permissionRefs adds perm:refunds.issue,
// availableActions adds { id: "issue_refund", riskLevel: "controlled_write" }.

Keep exploring

Other integration paths.

The host changes; the two seams do not. Whichever platform you start from, writes still pass through the governance gate — permission, policy, approval, audit.

Self-hosted commerce

nopCommerce

Self-hosted commerce with JWT auth and C# services. Swapping it for Shopify is an adapter-internal detail, invisible to the platform core.

Any stack

Build your own adapter

Support desks, internal tools, and multi-system single-tenant orchestration. Implement five methods in-process in TypeScript or out-of-process over HTTP in any language — C#, PHP, Python.

The easy case

ABP.io / ASP.NET Zero

If your product is built on ASP.NET Zero, the adapter is a thin translation layer over the auth, permissions, application services, and notifications ABP already ships.

Honest note

This is a documented integration approach with worked code — not a pre-built, install-and-go production connector. Governance, the adapter SDK, idempotency, and audit are built; the gateway-to-registered-adapter write dispatch is still maturing. See the full build-status honesty box →

Start your Shopify integration.

The adapter SDK and worked examples are in the docs. We'll walk your team through the two seams, the governance gate, and this path end to end.

Start integration Read the docs