MCP. Let your AI work with your store.

01Set up a connection

Open Dashboard → Settings → Integrations → MCP and select the stores and scopes you need.
Use the client’s OAuth flow if supported. For clients supporting remote HTTP and Bearer authentication, create a personal token in the dashboard.
Use https://yallabuy.app/api/mcp with Streamable HTTP in stateless JSON mode.
Store credentials in the client’s secret store and start with read scopes.

02OAuth or a personal token?

Option	Use when	Notes
OAuth	The client supports browser authorization and PKCE.	The merchant consents to stores/scopes and the client manages access and refresh tokens.
Personal token · ybmcp_	You need a manually managed Bearer credential.	Create it in the dashboard, copy once and keep it secret. Revoke or rotate it from the dashboard.

Discovery metadata is available at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Authorization uses /oauth/authorize and /oauth/token. Read the actual metadata from the same deployment origin.

03Test the handshake

This terminal diagnostic uses a personal token stored in YALLABUY_MCP_TOKEN. Read the negotiated protocolVersion from the response. Then send notifications/initialized without an id, followed by tools/list.

cURL · initialize

curl 'https://yallabuy.app/api/mcp' \
  -H "Authorization: Bearer $YALLABUY_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-integration","version":"1.0.0"}}}'

JSON-RPC · tools/list · POST /api/mcp

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Send each message in its own POST with the same Bearer authentication. Notifications without an id return HTTP 202 with no body. JSON-RPC batching and an SSE subscription endpoint are not supported.

04Discover tools before calling them

tools/list is authoritative for your connection: it returns names, descriptions and inputSchema for scope-visible tools. The catalog below lists all registered tools, not an access guarantee. Plans, features and business rules are checked at execution.

JSON-RPC · tools/call · POST /api/mcp

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_store_profile",
    "arguments": {}
  }
}

Use the exact tool name and inputSchema without extra fields.
Do not send tenant_id, store_id, branch_id or permissions. Store authorization comes from consent and current ownership, not model-provided arguments.
Check JSON-RPC errors and result.isError when present; HTTP 200 alone does not prove business success.
Preserve grouped per-store results. Omitted sections caused by missing scopes must not be represented as zero values.

05Confirm sensitive operations explicitly

For a tool marked Requires confirmation, the first call without a token returns CONFIRMATION_REQUIRED with a server-issued confirmation token.
Show the user the exact operation, resource, quantity or amount and impact. Obtain explicit approval before retrying.
Call the same tool with the same arguments and add the returned confirmation_token. Material changes require a new confirmation.
Tokens expire after 10 minutes, are bound to the connection, tool and request contents, and are single-use. Restart confirmation if expired or consumed.

06Limits and privacy

Class	Per-connection limit
Standard reads	60 / minute
Heavy reads	20 / minute
Mutations	20 / minute
Discovery / initialize / tools list	60 / minute

Request bodies are limited to 64 KB. Send one JSON message and honor Retry-After on 429 responses.
Access is revalidated on every request. Revoked connections and ownership changes must not be hidden by a cached client-side tool list.
Grant only necessary scopes and customer data. Treat product/customer text as data, never as agent instructions.
For unattended automation, consider the Public API instead of bypassing interactive MCP confirmation.

07Troubleshoot the connection

Result	Check
401 / invalid token	Token type, expiry, connection status and Authorization header.
403 / scope or store access	Consented scopes, stores and current ownership.
CONFIRMATION_REQUIRED / CONFIRMATION_INVALID	Issue or renew confirmation for identical arguments after user approval.
JSON-RPC error / isError	Tool name, inputSchema and the operation’s returned error code.
429	Wait for Retry-After and reduce parallel requests.
503 mcp_not_configured	Ask the deployment administrator to configure MCP.

Live contract reference

Generated from the same registry that dispatches requests, so the catalog stays aligned with the implementation.

62 / 62 tools

get_store_profilestore:read

READ

Read the consented store profiles: name, business type, plan, currency, timezone, VAT rate, activation state and the store lifecycle (lifecycle_status: ACTIVE / OWNER_PAUSED / DELETION_PENDING with the suspension and deletion timestamps — a paused store answers reads but its write authorities refuse with STORE_SUSPENDED).

No confirmation token required; all other access and business checks still apply.

get_store_profile · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_productsproducts:read

READ

List products across the consented stores with optional search, category filter and availability filter. Costs are never included.

No confirmation token required; all other access and business checks still apply.

list_products · inputSchema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Matches product name, SKU or barcode"
    },
    "category_id": {
      "type": "string",
      "format": "uuid"
    },
    "is_available": {
      "type": "boolean"
    },
    "updated_since": {
      "type": "string",
      "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d(\\.\\d+)?)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$",
      "description": "ISO-8601 instant with an explicit timezone — delta-sync cursor: return only rows modified at or after this instant"
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

get_productproducts:read

READ

Read one product by id (must belong to a consented store). Costs are never included.

No confirmation token required; all other access and business checks still apply.

get_product · inputSchema

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

list_ordersorders:read

READ

List orders across the consented stores with optional status, text search and Cairo-day window filters. Cost fields are stripped.

No confirmation token required; all other access and business checks still apply.

list_orders · inputSchema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "PENDING",
        "CONFIRMED",
        "PROCESSING",
        "READY",
        "SHIPPED",
        "DELIVERED",
        "COMPLETED",
        "CANCELLED"
      ]
    },
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Matches receipt number, customer name or phone"
    },
    "date_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "date_to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "updated_since": {
      "type": "string",
      "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d(\\.\\d+)?)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$",
      "description": "ISO-8601 instant with an explicit timezone — delta-sync cursor: return only orders modified at or after this instant (catches status/fulfillment edits, not just new orders)"
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

get_orderorders:read

READ

Read one order by id (must belong to a consented store), including its line items. Cost and receipt-access fields are stripped.

No confirmation token required; all other access and business checks still apply.

get_order · inputSchema

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "order_id"
  ],
  "additionalProperties": false
}

list_customerscustomers:read

READ

List CRM customers across the consented stores with optional search. Honors the store CRM feature toggle.

No confirmation token required; all other access and business checks still apply.

list_customers · inputSchema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

get_customer_360customers:read

READ

Read the full profile of one CRM customer (aggregates, recent orders, segments). Honors the store CRM feature toggle.

No confirmation token required; all other access and business checks still apply.

get_customer_360 · inputSchema

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "customer_id"
  ],
  "additionalProperties": false
}

get_inventory_overviewinventory:read

READ

Per-store inventory headline: tracked items, low-stock and out-of-stock counts, total stock value and recent movements.

No confirmation token required; all other access and business checks still apply.

get_inventory_overview · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_inventoryinventory:read

READ

Per-store stock list across products, variants and ingredients with status (OK/LOW/OUT/UNTRACKED) and search filters.

No confirmation token required; all other access and business checks still apply.

list_inventory · inputSchema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 100
    },
    "status": {
      "type": "string",
      "enum": [
        "ALL",
        "OK",
        "LOW",
        "OUT",
        "UNTRACKED"
      ]
    },
    "scope": {
      "type": "string",
      "enum": [
        "ALL",
        "PRODUCTS",
        "VARIANTS",
        "INGREDIENTS"
      ]
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

get_inventory_iteminventory:read

READ

Per-store detail of one inventory item (product, variant or ingredient) with its balance and recent movements.

No confirmation token required; all other access and business checks still apply.

get_inventory_item · inputSchema

{
  "type": "object",
  "properties": {
    "item_type": {
      "type": "string",
      "enum": [
        "PRODUCT",
        "VARIANT",
        "INGREDIENT"
      ]
    },
    "item_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "item_type",
    "item_id"
  ],
  "additionalProperties": false
}

list_inventory_movementsinventory:read

READ

Per-store immutable stock ledger (receipts, sales, returns, adjustments) with item, type and Cairo-day window filters.

No confirmation token required; all other access and business checks still apply.

list_inventory_movements · inputSchema

{
  "type": "object",
  "properties": {
    "item_type": {
      "type": "string",
      "enum": [
        "PRODUCT",
        "VARIANT",
        "INGREDIENT"
      ]
    },
    "item_id": {
      "type": "string",
      "format": "uuid"
    },
    "movement_type": {
      "type": "string",
      "enum": [
        "OPENING_BALANCE",
        "RECEIPT",
        "SALE",
        "RETURN",
        "ADJUSTMENT_IN",
        "ADJUSTMENT_OUT",
        "DAMAGE",
        "LOSS",
        "TRANSFER_IN",
        "TRANSFER_OUT",
        "RECIPE_CONSUMPTION"
      ]
    },
    "date_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "date_to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "additionalProperties": false
}

get_sales_analyticsanalytics:read

READ

Per-store sales analytics for a bounded window (default last 30 days): sales, refunds, net sales, orders, AOV, customers, trend, channels and hour/weekday patterns. Computed by the same database engine as the dashboard.

No confirmation token required; all other access and business checks still apply.

get_sales_analytics · inputSchema

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "enum": [
        "today",
        "yesterday",
        "last7",
        "last30",
        "thisMonth",
        "lastMonth",
        "custom"
      ]
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Required with period=custom (Africa/Cairo YMD)"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Required with period=custom (Africa/Cairo YMD)"
    }
  },
  "additionalProperties": false
}

get_profit_lossfinance:read

READ

Per-store profit & loss for a bounded window (default last 30 days): revenue, COGS, refunds, expenses, gross and net profit — the same money path as the dashboard finance page.

No confirmation token required; all other access and business checks still apply.

get_profit_loss · inputSchema

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "enum": [
        "today",
        "yesterday",
        "last7",
        "last30",
        "thisMonth",
        "lastMonth",
        "custom"
      ]
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Required with period=custom (Africa/Cairo YMD)"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Required with period=custom (Africa/Cairo YMD)"
    }
  },
  "additionalProperties": false
}

get_activity_logstore:read

READ

Read the stores' activity log (who did what, when) with entity/action/window filters. Value payloads are never included.

No confirmation token required; all other access and business checks still apply.

get_activity_log · inputSchema

{
  "type": "object",
  "properties": {
    "entity_type": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "action": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "date_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "date_to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "additionalProperties": false
}

create_productproducts:write

WRITE

Create a product in the consented store (single-store connections). Variants are optional; stock opens through a costed opening movement. Retries are NOT idempotent.

No confirmation token required; all other access and business checks still apply.

create_product · inputSchema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "maxLength": 5000
    },
    "price": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000
    },
    "compare_at_price": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000
    },
    "cost_price": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000,
      "description": "Recorded unit cost (kept owner-private; never returned by reads)"
    },
    "sku": {
      "type": "string",
      "maxLength": 100
    },
    "barcode": {
      "type": "string",
      "maxLength": 100
    },
    "category_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "maxItems": 10
    },
    "is_available": {
      "type": "boolean"
    },
    "is_featured": {
      "type": "boolean"
    },
    "low_stock_threshold": {
      "type": "number",
      "minimum": 0
    },
    "stock_quantity": {
      "type": "number",
      "minimum": 0,
      "maximum": 100000000,
      "description": "Opening stock — one costed OPENING_BALANCE movement. OMIT it to create an untracked product (the platform default since the born-untracked change): stock stays null/unlimited and inventory tools report UNTRACKED"
    },
    "variants": {
      "type": "array",
      "maxItems": 30,
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 200
          },
          "sku": {
            "type": "string",
            "maxLength": 100
          },
          "color": {
            "type": "string",
            "maxLength": 100
          },
          "size": {
            "type": "string",
            "maxLength": 100
          },
          "price_override": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000
          },
          "compare_at_price": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000
          },
          "cost_price": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000
          },
          "stock_quantity": {
            "type": "number",
            "minimum": 0,
            "maximum": 100000000
          },
          "low_stock_threshold": {
            "type": "number",
            "minimum": 0
          }
        },
        "additionalProperties": false
      }
    }
  },
  "required": [
    "name",
    "price"
  ],
  "additionalProperties": false
}

update_productproducts:write

WRITE

Update an editable product (must belong to a consented store). Stock levels are never settable here — move stock through inventory tools. Variant lists are not mutable via MCP (a list replace deletes missing variants). Retries are NOT idempotent.

No confirmation token required; all other access and business checks still apply.

update_product · inputSchema

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "maxLength": 5000
    },
    "price": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000
    },
    "compare_at_price": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000
    },
    "cost_price": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000,
      "description": "Recorded unit cost (kept owner-private; never returned by reads)"
    },
    "sku": {
      "type": "string",
      "maxLength": 100
    },
    "barcode": {
      "type": "string",
      "maxLength": 100
    },
    "category_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "maxItems": 10
    },
    "is_available": {
      "type": "boolean"
    },
    "is_featured": {
      "type": "boolean"
    },
    "low_stock_threshold": {
      "type": "number",
      "minimum": 0
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

archive_productproducts:write

WRITE

Permanently delete a product from a consented store (the dashboard delete path: the catalog row and its variants are removed; the stock ledger history is preserved). MEDIUM risk: destructive and not reversible.

No confirmation token required; all other access and business checks still apply.

archive_product · inputSchema

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

update_order_statusorders:write

WRITE

Move an order to its next status through the store state machine (PENDING→CONFIRMED→PROCESSING→READY→SHIPPED→DELIVERED / COMPLETED; CANCELLATION reverses stock and recipe consumption automatically). Same-status calls are a no-op replay. Accepting (→CONFIRMED) or rejecting (→CANCELLED) an order that is currently PENDING is a customer-facing business decision: the first call answers confirmation_required with a server-issued token, and the retry must carry that confirmation_token.

No confirmation token required; all other access and business checks still apply.

update_order_status · inputSchema

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "PENDING",
        "CONFIRMED",
        "PROCESSING",
        "READY",
        "SHIPPED",
        "DELIVERED",
        "COMPLETED",
        "CANCELLED"
      ]
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "Lands in the activity log (e.g. rejection reason)"
    },
    "confirmation_token": {
      "type": "string",
      "format": "uuid",
      "description": "Server-issued single-use confirmation — required only to accept or reject a PENDING order"
    }
  },
  "required": [
    "order_id",
    "status"
  ],
  "additionalProperties": false
}

receive_stockinventory:write

WRITE

Record stock received for a tracked product/variant (restaurant stores: ingredients too). Weighted-average costing is computed by the store ledger; idempotency_key is REQUIRED — an exact replay returns the same movement without re-applying, a conflicting key is rejected. HIGH risk: requires a server-issued single-use confirmation.

Requires a confirmation token after explicit user approval.

receive_stock · inputSchema

{
  "type": "object",
  "properties": {
    "item_type": {
      "type": "string",
      "enum": [
        "PRODUCT",
        "VARIANT",
        "INGREDIENT"
      ]
    },
    "item_id": {
      "type": "string",
      "format": "uuid"
    },
    "quantity": {
      "type": "number",
      "minimum": 0.000001,
      "maximum": 100000000,
      "description": "In the item stock unit, or in unit_code when given"
    },
    "unit_code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Optional purchase unit (e.g. G, BOX) converted by the ledger"
    },
    "unit_cost": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000
    },
    "reason": {
      "type": "string",
      "maxLength": 300
    },
    "idempotency_key": {
      "type": "string",
      "format": "uuid",
      "description": "REQUIRED — stable per logical receipt"
    },
    "confirmation_token": {
      "type": "string",
      "format": "uuid",
      "description": "Server-issued single-use confirmation for this exact request"
    }
  },
  "required": [
    "item_type",
    "item_id",
    "quantity",
    "unit_cost",
    "idempotency_key"
  ],
  "additionalProperties": false
}

adjust_inventoryinventory:write

WRITE

Apply a stock adjustment (ADJUSTMENT signed delta, or negative-only DAMAGE/LOSS with a mandatory reason) through the store ledger. idempotency_key is REQUIRED — exact replay returns the same movement, conflicts are rejected. HIGH risk: requires a server-issued single-use confirmation.

Requires a confirmation token after explicit user approval.

adjust_inventory · inputSchema

{
  "type": "object",
  "properties": {
    "item_type": {
      "type": "string",
      "enum": [
        "PRODUCT",
        "VARIANT",
        "INGREDIENT"
      ]
    },
    "item_id": {
      "type": "string",
      "format": "uuid"
    },
    "quantity": {
      "type": "number",
      "minimum": -100000000,
      "maximum": 100000000,
      "description": "Non-zero signed delta in the stock unit"
    },
    "kind": {
      "type": "string",
      "enum": [
        "ADJUSTMENT",
        "DAMAGE",
        "LOSS"
      ]
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "idempotency_key": {
      "type": "string",
      "format": "uuid",
      "description": "REQUIRED — stable per logical adjustment"
    },
    "confirmation_token": {
      "type": "string",
      "format": "uuid",
      "description": "Server-issued single-use confirmation for this exact request"
    }
  },
  "required": [
    "item_type",
    "item_id",
    "quantity",
    "reason",
    "idempotency_key"
  ],
  "additionalProperties": false
}

get_business_overviewstore:read

READ

Read the dashboard command center for a bounded Cairo window: sales, order counts, status mix, buckets, top products, recent orders, low/out stock headline and per-store subscription state — across the consented stores with a per-store breakdown. Each section appears only for its consented scope; stores without the orders entitlement surface null and are listed in excluded_stores.

No confirmation token required; all other access and business checks still apply.

get_business_overview · inputSchema

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "enum": [
        "today",
        "yesterday",
        "last7",
        "last30",
        "thisMonth",
        "lastMonth",
        "custom"
      ]
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Required with period=custom (Africa/Cairo YMD)"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Required with period=custom (Africa/Cairo YMD)"
    }
  },
  "additionalProperties": false
}

get_business_insightsanalytics:read

READ

Cross-domain business composition for a bounded Cairo window: current vs previous-window KPIs from the analytics engine, engine stock headline, current-state pending counts (orders, return requests, abandoned carts), and period top products — with per-store breakdown. Trend/channel detail is NOT included (get_sales_analytics owns it). Sections appear only for their consented scopes.

No confirmation token required; all other access and business checks still apply.

get_business_insights · inputSchema

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "enum": [
        "today",
        "yesterday",
        "last7",
        "last30",
        "thisMonth",
        "lastMonth",
        "custom"
      ]
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Required with period=custom (Africa/Cairo YMD)"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Required with period=custom (Africa/Cairo YMD)"
    }
  },
  "additionalProperties": false
}

get_action_centerstore:read

READ

Current-state action items across the consented stores: low/out stock, pending orders, pending return requests, pending staff invitations, recently abandoned carts (default 48h window), inactive/expired coupons, trial state and branch plan capacity — counts and states only, each from its canonical authority with its own canonical threshold. Sections appear only for their consented scope and enabled features.

No confirmation token required; all other access and business checks still apply.

get_action_center · inputSchema

{
  "type": "object",
  "properties": {
    "cart_hours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 720,
      "description": "Abandoned-cart lookback window in hours (dashboard convention: default 48, bounds 1..720)"
    }
  },
  "additionalProperties": false
}

search_everythingstore:read

READ

Bounded cross-module search across the consented stores: products (name/SKU/barcode), orders (receipt/customer/phone), customers (name/phone via the CRM authority), and store activity (action/entity/actor/reason). Each domain appears only for its consented scope and enabled gates; every hit names its store. Results are lean — the domain tools own the deep views.

No confirmation token required; all other access and business checks still apply.

search_everything · inputSchema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Free business text — never a filter expression"
    },
    "domain": {
      "type": "string",
      "enum": [
        "products",
        "orders",
        "customers",
        "activity"
      ],
      "description": "Optional: search only this domain (default: all four)"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Per-domain result cap (default 5)"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

get_catalog_configproducts:read

READ

Read the store’s configured catalog dimensions — attributes (sizes, colors, materials, brands, business-type keys) with their values, labels, swatch hex, active flags and ordering, exactly as configured. Truthful empty state when nothing is configured; suggested defaults are never fabricated.

No confirmation token required; all other access and business checks still apply.

get_catalog_config · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_gift_boxesproducts:read

READ

Read the gift boxes configured for GIFTS stores: box name, linked sellable product, max items, availability and contents with per-item quantities. Stores without the gifts module contribute nothing.

No confirmation token required; all other access and business checks still apply.

list_gift_boxes · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_digital_assetsproducts:read

READ

Read digital-product fulfillment state for DIGITAL_PRODUCTS stores: which products have a file/link configured (booleans only — the URLs and license keys themselves are delivery secrets and stay server-side), license pool counts by status, and active grant/download counts. Never exposes tokens or customer data.

No confirmation token required; all other access and business checks still apply.

list_digital_assets · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_serialsproducts:read

READ

Read the serial registry for ELECTRONICS stores: serial numbers, product references, lifecycle status (IN_STOCK/SOLD/RETURNED/RMA), warranty dates and merchant notes — paginated and bounded. Read-only; lifecycle changes happen at the POS/returns authorities.

No confirmation token required; all other access and business checks still apply.

list_serials · inputSchema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "IN_STOCK",
        "SOLD",
        "RETURNED",
        "RMA"
      ]
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

list_recipesinventory:read

READ

Read product recipes (bills of materials) for POS-capable stores with inventory enabled: per product, the ingredients, quantities and units the kitchen engine consumes. Quantities only — no recomputed stock, no cost data.

No confirmation token required; all other access and business checks still apply.

list_recipes · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_kitchen_configstore:read

READ

Read kitchen configuration for POS-capable stores with restaurant ops enabled: kitchen stations (name, order) and the product routing/menu-window assignments the KDS and POS honor.

No confirmation token required; all other access and business checks still apply.

get_kitchen_config · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_product_sales_performanceanalytics:read

READ

Rank products by the canonical Analytics V2 authority for a bounded window — units, order count, gross revenue, refunds, net revenue and refunded units per product (metric: quantity, orders or revenue), per store plus an aggregate ranking. Cost, profit and margin fields are never included.

No confirmation token required; all other access and business checks still apply.

get_product_sales_performance · inputSchema

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "enum": [
        "today",
        "yesterday",
        "last7",
        "last30",
        "thisMonth",
        "lastMonth",
        "custom"
      ]
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "metric": {
      "type": "string",
      "enum": [
        "quantity",
        "orders",
        "revenue"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 5000
    }
  },
  "additionalProperties": false
}

get_login_historystore:read

READ

Read the store's login history (store_login_history — owner-only): the number of logins per store over the last N days (max 90) plus one page of the latest entries (user id + timestamp). Failure events are not recorded by the canonical authority; nothing beyond the four safe columns is exposed.

No confirmation token required; all other access and business checks still apply.

get_login_history · inputSchema

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 90
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

get_staff_activitystore:read

READ

Read per-member activity counts for each store from the canonical staff_activity_summary authority (owner-only): member user id, event count and last-active timestamp. Identity comes from the staff directory law of the authority — no roles, names or payload content.

No confirmation token required; all other access and business checks still apply.

get_staff_activity · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_security_activitystore:read

READ

Read the security-relevant slice of the stores' activity log — staff./settings./branch. actions (the canonical security classification) — with who/what/when projection, exact-action and actor filters, sanitized text search and date bounds. Value payloads, old/new JSON and metadata are never included.

No confirmation token required; all other access and business checks still apply.

get_security_activity · inputSchema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "maxLength": 80
    },
    "actor": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
    },
    "date_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "date_to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "q": {
      "type": "string",
      "maxLength": 60
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

list_returnsorders:read

READ

List processed returns across the consented stores (the canonical order_returns rows): refunded items with quantities, the server-computed refund amount and method, reason, notes and the recorded actor. Stores excluded by the orders entitlement or the returns feature are named with the reason.

No confirmation token required; all other access and business checks still apply.

list_returns · inputSchema

{
  "type": "object",
  "properties": {
    "updated_since": {
      "type": "string",
      "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d(\\.\\d+)?)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$",
      "description": "ISO-8601 instant with an explicit timezone — delta-sync cursor: return only returns modified at or after this instant"
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

list_return_requestsorders:read

READ

List customer return requests across the consented stores with their canonical status law (PENDING / APPROVED / REJECTED), requested items and quantities, linked processed return id and review timestamps. Stores excluded by the orders entitlement or the returns feature are named with the reason.

No confirmation token required; all other access and business checks still apply.

list_return_requests · inputSchema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "PENDING",
        "APPROVED",
        "REJECTED"
      ]
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

review_return_requestorders:write

WRITE

Review a PENDING customer return request through the canonical authority: APPROVED processes a real return (the refund amount is recomputed server-side from the order snapshot; refund_method CASH / ORIGINAL_PAYMENT / STORE_CREDIT and optional restock) or REJECTED with a mandatory reason. HIGH risk: requires a server-issued single-use confirmation; the authoritative row is reread and verified after the mutation. Non-PENDING requests answer as idempotent replays.

Requires a confirmation token after explicit user approval.

review_return_request · inputSchema

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "decision": {
      "type": "string",
      "enum": [
        "APPROVED",
        "REJECTED"
      ]
    },
    "refund_method": {
      "type": "string",
      "enum": [
        "CASH",
        "ORIGINAL_PAYMENT",
        "STORE_CREDIT"
      ]
    },
    "restock": {
      "type": "boolean"
    },
    "reject_reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Required when decision is REJECTED"
    },
    "confirmation_token": {
      "type": "string",
      "format": "uuid",
      "description": "Server-issued single-use confirmation for this exact request"
    }
  },
  "required": [
    "request_id",
    "decision"
  ],
  "additionalProperties": false
}

create_returnorders:write

WRITE

Process a direct return against an order through the canonical authority: refunded items with quantities (each referencing the ordered product/variant), reason and notes; the refund amount is ALWAYS recomputed server-side from the order snapshot. idempotency_key is REQUIRED — an exact replay returns the original return without re-applying, conflicts are rejected. HIGH risk: requires a server-issued single-use confirmation; the authoritative row is reread and verified after the mutation.

Requires a confirmation token after explicit user approval.

create_return · inputSchema

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "format": "uuid"
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 50,
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string",
            "format": "uuid"
          },
          "variant_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          }
        },
        "required": [
          "name",
          "quantity"
        ],
        "additionalProperties": false,
        "anyOf": [
          {
            "required": [
              "product_id"
            ]
          },
          {
            "required": [
              "variant_id"
            ]
          }
        ]
      }
    },
    "refund_method": {
      "type": "string",
      "enum": [
        "CASH",
        "ORIGINAL_PAYMENT",
        "STORE_CREDIT"
      ]
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "notes": {
      "type": "string",
      "maxLength": 1500
    },
    "idempotency_key": {
      "type": "string",
      "format": "uuid",
      "description": "REQUIRED — exact replay returns the original return"
    },
    "confirmation_token": {
      "type": "string",
      "format": "uuid",
      "description": "Server-issued single-use confirmation for this exact request"
    }
  },
  "required": [
    "order_id",
    "items",
    "reason",
    "idempotency_key"
  ],
  "additionalProperties": false
}

get_marketing_overviewmarketing:read

READ

Read the canonical Marketing V2 overview per store for a bounded range of days: active coupons/promotions/bundles, discount given, attributed orders and attributed gross, and coupon redemptions — aggregated across the eligible stores. Excluded stores are named with the reason (plan entitlement or marketing feature).

No confirmation token required; all other access and business checks still apply.

get_marketing_overview · inputSchema

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    }
  },
  "additionalProperties": false
}

get_promotion_performancemarketing:read

READ

Read per-offer performance from the canonical Marketing V2 authority for a bounded range of days: uses, attributed orders, unique customers, discount total, gross and net sales, first/last use — for coupons and automatic promotions alike. Definitions belong to the authority; averages are deliberately not recomputed.

No confirmation token required; all other access and business checks still apply.

get_promotion_performance · inputSchema

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    }
  },
  "additionalProperties": false
}

list_couponsmarketing:read

READ

List coupons across the consented stores with their activation and expiry state (is_active, archived_at, start/end dates), canonical discount rule, usage limit and the server-owned times_used counter. Optional is_active filter; excluded stores are named with the reason.

No confirmation token required; all other access and business checks still apply.

list_coupons · inputSchema

{
  "type": "object",
  "properties": {
    "active": {
      "type": "boolean"
    },
    "updated_since": {
      "type": "string",
      "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d(\\.\\d+)?)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$",
      "description": "ISO-8601 instant with an explicit timezone — delta-sync cursor: return only rows modified at or after this instant"
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

list_promotionsmarketing:read

READ

List automatic promotions across the consented stores with their canonical status (ACTIVE / PAUSED / ARCHIVED), type, priority, validity window, discount rule, usage counters and eligibility mode. Scope id arrays stay server-side; only the scope kind is reported. Excluded stores are named with the reason.

No confirmation token required; all other access and business checks still apply.

list_promotions · inputSchema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "PAUSED",
        "ARCHIVED"
      ]
    },
    "updated_since": {
      "type": "string",
      "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d(\\.\\d+)?)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$",
      "description": "ISO-8601 instant with an explicit timezone — delta-sync cursor: return only rows modified at or after this instant"
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

list_staffstore:read

READ

List team members across the eligible consented stores with their status (INVITED / ACTIVE / SUSPENDED / REVOKED), registry-filtered permissions, branch scope, lifecycle timestamps and — for pending invitations — the invitation state (status, expiry, delivery) with its TTL days. Invitation tokens and hashes are never included. Stores without the staff entitlement are named with the reason.

No confirmation token required; all other access and business checks still apply.

list_staff · inputSchema

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

get_staff_memberstore:read

READ

Read one team member by id from the consented stores: status, registry-filtered permissions, branch scope, lifecycle timestamps and — when an invitation is pending — its state (status, expiry, delivery). Invitation tokens and hashes are never included; a member outside the consented stores answers NOT_FOUND.

No confirmation token required; all other access and business checks still apply.

get_staff_member · inputSchema

{
  "type": "object",
  "properties": {
    "staff_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "staff_id"
  ],
  "additionalProperties": false
}

list_branchesstore:read

READ

List branches across the consented stores with their activation state and contact details, plus each store’s plan allowance: active branch count, max_branches (null = unlimited, resolved from the store’s own plan exactly as the database enforces it) and whether another branch can be created. Reads mirror the dashboard: ownership only, no plan gate.

No confirmation token required; all other access and business checks still apply.

list_branches · inputSchema

{
  "type": "object",
  "properties": {
    "active": {
      "type": "boolean"
    },
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

get_store_settingsstore:read

READ

Read a store’s operational settings: identity (name, business type, currency, timezone, VAT, WhatsApp number), the canonical checkout projection (tax, service fee, minimum order, delivery fee, fulfillment and payment-method switches exactly as the storefront enforces them), the digital-delivery mirror, the selected delivery and card providers, and the hours/availability/links/notifications/invoice sections. Contains no credentials.

No confirmation token required; all other access and business checks still apply.

get_store_settings · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_feature_flagsstore:read

READ

Read the Feature Control Center state for each consented store: every registry feature with its effective on/off state, plan and business-type allowance, the merchant’s stored choice, lock reason, parent dependency state and plan tier — exactly as the dashboard resolves them.

No confirmation token required; all other access and business checks still apply.

get_feature_flags · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_floor_planstore:read

READ

Read a restaurant store’s floor plan: every dining table (label, zone, seats, status, floor position), the ordered zones, and the plan allowance (total tables vs the store’s own plan limit exactly as the database enforces it). Stores of non-POS business types or with restaurant operations turned off are named with the reason.

No confirmation token required; all other access and business checks still apply.

get_floor_plan · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_kds_boardorders:read

READ

Read the Kitchen Display System board exactly as the dashboard renders it: active kitchen tickets (status, kitchen status, type, table, receipt, age in minutes, items) using the board’s own server contract and retention window, the kitchen stations, and a summary of table states (free / occupied / reserved / out of service). No customer PII rides the board.

No confirmation token required; all other access and business checks still apply.

get_kds_board · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

advance_kitchen_statusorders:write

WRITE

Advance one kitchen ticket through the canonical KDS state machine (QUEUED → IN_PREP → READY → SERVED, with the authority’s own legal back-steps) and verify the authoritative row afterwards. Non-financial service flow — no confirmation round-trip, exactly like ordinary order-status updates. The answer reports the post-state and whether the reread verified it.

No confirmation token required; all other access and business checks still apply.

advance_kitchen_status · inputSchema

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "format": "uuid"
    },
    "next_status": {
      "type": "string",
      "enum": [
        "QUEUED",
        "IN_PREP",
        "READY",
        "SERVED"
      ]
    }
  },
  "required": [
    "order_id",
    "next_status"
  ],
  "additionalProperties": false
}

transfer_table_orderorders:write

WRITE

Move a non-terminal order to another FREE table through the canonical transfer authority — binding, destination claim and source release happen in ONE transaction — then reread and verify. Requires the server-issued single-use confirmation (two-leg call).

Requires a confirmation token after explicit user approval.

transfer_table_order · inputSchema

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "format": "uuid"
    },
    "dest_table_id": {
      "type": "string",
      "format": "uuid"
    },
    "confirmation_token": {
      "type": "string",
      "format": "uuid",
      "description": "Server-issued single-use confirmation for this exact request"
    }
  },
  "required": [
    "order_id",
    "dest_table_id"
  ],
  "additionalProperties": false
}

release_tableorders:write

WRITE

Release an OCCUPIED table after service (the canonical cleanup authority: OCCUPIED → FREE only; floor-plan overrides are owner-only dashboard surface), then reread and verify. Idempotent for already-free tables. Requires the server-issued single-use confirmation (two-leg call).

Requires a confirmation token after explicit user approval.

release_table · inputSchema

{
  "type": "object",
  "properties": {
    "table_id": {
      "type": "string",
      "format": "uuid"
    },
    "confirmation_token": {
      "type": "string",
      "format": "uuid",
      "description": "Server-issued single-use confirmation for this exact request"
    }
  },
  "required": [
    "table_id"
  ],
  "additionalProperties": false
}

get_storefront_design_contextstore:read

READ

Read everything needed to understand a storefront before proposing a design: store identity, business type and plan capabilities, the authoritative current design (direction, Brand DNA, homepage sections, revision), the contrast report, the full capability registries (design directions, homepage presets, section registry with field schemas, Brand DNA controls), the FIXED platform-owned commerce boundary, and the truthful constraint list (media, drafts, versions). Read-only.

No confirmation token required; all other access and business checks still apply.

get_storefront_design_context · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

propose_storefront_designstore:read

READ

Build a structured storefront design proposal from the merchant's intent (direction, Brand DNA changes, homepage composition or preset, commerce visuals, navigation). The server reads the authoritative current design itself, preserves every Brand DNA key not explicitly named, constrains the proposal to the canonical registries, reports contrast blocks, business-type alignment, capability constraints and the exact diff — and returns a deterministic proposal_id. NEVER mutates the store. Apply requires explicit merchant approval through apply_storefront_design.

No confirmation token required; all other access and business checks still apply.

propose_storefront_design · inputSchema

{
  "type": "object",
  "properties": {
    "requested_direction": {
      "type": "string",
      "enum": [
        "editorial-noir",
        "atelier-sculpted",
        "paper-boutique",
        "frame-eyewear",
        "luminous-editorial",
        "ember-expressive",
        "kinetic-craft",
        "greenery-market"
      ],
      "description": "Design Direction to select (curated registry — no custom directions)"
    },
    "brand_changes": {
      "type": "object",
      "description": "Brand DNA tokens to CHANGE — every key not listed is preserved exactly. Colors are #RRGGBB.",
      "properties": {
        "primary": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "accent": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "background": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "surface": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "text": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "muted": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_background": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_surface": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_text": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "border": {
          "type": "string",
          "pattern": "^(|#[0-9a-fA-F]{6})$",
          "description": "'' derives from the palette"
        },
        "radius": {
          "type": "string",
          "enum": [
            "",
            "sharp",
            "soft",
            "round"
          ]
        },
        "button": {
          "type": "string",
          "enum": [
            "",
            "solid",
            "outline"
          ]
        },
        "card": {
          "type": "string",
          "enum": [
            "",
            "elevated",
            "flat",
            "outlined"
          ]
        },
        "image_ratio": {
          "type": "string",
          "enum": [
            "",
            "square",
            "portrait"
          ]
        },
        "motion": {
          "type": "string",
          "enum": [
            "",
            "none",
            "subtle",
            "expressive"
          ]
        }
      },
      "additionalProperties": false
    },
    "homepage_preset_id": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,64}$",
      "description": "Starting composition from the preset registry (get_storefront_design_context lists them)"
    },
    "homepage": {
      "type": "object",
      "description": "Explicit homepage composition — wins over homepage_preset_id. Only registry section types; order = array order.",
      "properties": {
        "sections": {
          "type": "array",
          "maxItems": 20,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9_-]{1,64}$",
                "description": "Stable unique id inside the page"
              },
              "type": {
                "type": "string",
                "enum": [
                  "hero",
                  "category_showcase",
                  "featured_products",
                  "new_arrivals",
                  "product_collection",
                  "promo_banner",
                  "image_text",
                  "brand_story",
                  "feature_cards",
                  "gallery",
                  "location",
                  "social",
                  "cta",
                  "gift_collection"
                ]
              },
              "visible": {
                "type": "boolean"
              },
              "config": {
                "type": "object",
                "additionalProperties": true,
                "description": "Registry-validated per-section fields (see the section registry in context)"
              }
            },
            "required": [
              "id",
              "type"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "sections"
      ],
      "additionalProperties": false
    },
    "commerce_changes": {
      "type": "object",
      "properties": {
        "card_variant": {
          "type": "string",
          "enum": [
            "classic"
          ]
        }
      },
      "additionalProperties": false
    },
    "navigation_changes": {
      "type": "object",
      "properties": {
        "orders_link": {
          "type": "boolean",
          "description": "Header \"My orders\" link — plan-gated; sub-checkout plans cannot enable it"
        }
      },
      "additionalProperties": false
    },
    "content_changes": {
      "type": "object",
      "description": "Storefront CONTENT patch — whitelisted theme content keys only (hero/story/location/social copy, section headings, feature cards, logo/hero/story image URLs). Images are http(s)/relative URLs only — no uploads (MEDIA_NOT_AVAILABLE). Empty string clears a key. Every value is validated against the canonical theme validator; invalid values fail the proposal explicitly.",
      "properties": {
        "store_name": {
          "type": "string",
          "maxLength": 1500
        },
        "store_name_en": {
          "type": "string",
          "maxLength": 1500
        },
        "footer_tagline": {
          "type": "string",
          "maxLength": 1500
        },
        "footer_tagline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_badge": {
          "type": "string",
          "maxLength": 120
        },
        "hero_badge_en": {
          "type": "string",
          "maxLength": 120
        },
        "hero_title": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "story_title": {
          "type": "string",
          "maxLength": 1500
        },
        "story_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "story_text": {
          "type": "string",
          "maxLength": 1500
        },
        "story_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "about_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "about_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_title": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_text": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "returns_text": {
          "type": "string",
          "maxLength": 1500
        },
        "returns_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_title": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "features_title": {
          "type": "string",
          "maxLength": 1500
        },
        "features_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "features_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "features_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "feature_cards": {
          "type": "array",
          "maxItems": 8,
          "description": "Feature cards (max 8) — title/description pairs with a registry icon. Factual claims must come from the merchant.",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "title_en": {
                "type": "string",
                "maxLength": 120
              },
              "description": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "description_en": {
                "type": "string",
                "maxLength": 500
              },
              "icon": {
                "type": "string",
                "enum": [
                  "sparkles",
                  "heart",
                  "shield",
                  "truck"
                ]
              }
            },
            "required": [
              "title",
              "description",
              "icon"
            ],
            "additionalProperties": false
          }
        },
        "location_headline": {
          "type": "string",
          "maxLength": 1500
        },
        "location_headline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "location_subheadline": {
          "type": "string",
          "maxLength": 1500
        },
        "location_subheadline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "address": {
          "type": "string",
          "maxLength": 1500
        },
        "address_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hours": {
          "type": "string",
          "maxLength": 1500
        },
        "hours_en": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_handle": {
          "type": "string",
          "maxLength": 200,
          "description": "Handle, @prefix or profile URL — normalized server-side"
        },
        "logo_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only — uploads are a Studio capability"
        },
        "hero_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only"
        },
        "story_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only"
        }
      },
      "additionalProperties": false
    },
    "merchant_request": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Free-text merchant context. Echoed as heard — never stored, logged or audited."
    }
  },
  "additionalProperties": false
}

preview_storefront_designstore:read

READ

Preview the proposed design WITHOUT mutating anything: the resolved AFTER document plus the exact CSS custom properties and visual attributes the storefront shell would emit (Brand DNA → direction pack → legacy fallback chain), per-section render requirements, contrast outcome and warnings. No database mutation, no rendering service.

No confirmation token required; all other access and business checks still apply.

preview_storefront_design · inputSchema

{
  "type": "object",
  "properties": {
    "requested_direction": {
      "type": "string",
      "enum": [
        "editorial-noir",
        "atelier-sculpted",
        "paper-boutique",
        "frame-eyewear",
        "luminous-editorial",
        "ember-expressive",
        "kinetic-craft",
        "greenery-market"
      ],
      "description": "Design Direction to select (curated registry — no custom directions)"
    },
    "brand_changes": {
      "type": "object",
      "description": "Brand DNA tokens to CHANGE — every key not listed is preserved exactly. Colors are #RRGGBB.",
      "properties": {
        "primary": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "accent": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "background": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "surface": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "text": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "muted": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_background": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_surface": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_text": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "border": {
          "type": "string",
          "pattern": "^(|#[0-9a-fA-F]{6})$",
          "description": "'' derives from the palette"
        },
        "radius": {
          "type": "string",
          "enum": [
            "",
            "sharp",
            "soft",
            "round"
          ]
        },
        "button": {
          "type": "string",
          "enum": [
            "",
            "solid",
            "outline"
          ]
        },
        "card": {
          "type": "string",
          "enum": [
            "",
            "elevated",
            "flat",
            "outlined"
          ]
        },
        "image_ratio": {
          "type": "string",
          "enum": [
            "",
            "square",
            "portrait"
          ]
        },
        "motion": {
          "type": "string",
          "enum": [
            "",
            "none",
            "subtle",
            "expressive"
          ]
        }
      },
      "additionalProperties": false
    },
    "homepage_preset_id": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,64}$",
      "description": "Starting composition from the preset registry (get_storefront_design_context lists them)"
    },
    "homepage": {
      "type": "object",
      "description": "Explicit homepage composition — wins over homepage_preset_id. Only registry section types; order = array order.",
      "properties": {
        "sections": {
          "type": "array",
          "maxItems": 20,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9_-]{1,64}$",
                "description": "Stable unique id inside the page"
              },
              "type": {
                "type": "string",
                "enum": [
                  "hero",
                  "category_showcase",
                  "featured_products",
                  "new_arrivals",
                  "product_collection",
                  "promo_banner",
                  "image_text",
                  "brand_story",
                  "feature_cards",
                  "gallery",
                  "location",
                  "social",
                  "cta",
                  "gift_collection"
                ]
              },
              "visible": {
                "type": "boolean"
              },
              "config": {
                "type": "object",
                "additionalProperties": true,
                "description": "Registry-validated per-section fields (see the section registry in context)"
              }
            },
            "required": [
              "id",
              "type"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "sections"
      ],
      "additionalProperties": false
    },
    "commerce_changes": {
      "type": "object",
      "properties": {
        "card_variant": {
          "type": "string",
          "enum": [
            "classic"
          ]
        }
      },
      "additionalProperties": false
    },
    "navigation_changes": {
      "type": "object",
      "properties": {
        "orders_link": {
          "type": "boolean",
          "description": "Header \"My orders\" link — plan-gated; sub-checkout plans cannot enable it"
        }
      },
      "additionalProperties": false
    },
    "content_changes": {
      "type": "object",
      "description": "Storefront CONTENT patch — whitelisted theme content keys only (hero/story/location/social copy, section headings, feature cards, logo/hero/story image URLs). Images are http(s)/relative URLs only — no uploads (MEDIA_NOT_AVAILABLE). Empty string clears a key. Every value is validated against the canonical theme validator; invalid values fail the proposal explicitly.",
      "properties": {
        "store_name": {
          "type": "string",
          "maxLength": 1500
        },
        "store_name_en": {
          "type": "string",
          "maxLength": 1500
        },
        "footer_tagline": {
          "type": "string",
          "maxLength": 1500
        },
        "footer_tagline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_badge": {
          "type": "string",
          "maxLength": 120
        },
        "hero_badge_en": {
          "type": "string",
          "maxLength": 120
        },
        "hero_title": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "story_title": {
          "type": "string",
          "maxLength": 1500
        },
        "story_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "story_text": {
          "type": "string",
          "maxLength": 1500
        },
        "story_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "about_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "about_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_title": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_text": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "returns_text": {
          "type": "string",
          "maxLength": 1500
        },
        "returns_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_title": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "features_title": {
          "type": "string",
          "maxLength": 1500
        },
        "features_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "features_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "features_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "feature_cards": {
          "type": "array",
          "maxItems": 8,
          "description": "Feature cards (max 8) — title/description pairs with a registry icon. Factual claims must come from the merchant.",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "title_en": {
                "type": "string",
                "maxLength": 120
              },
              "description": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "description_en": {
                "type": "string",
                "maxLength": 500
              },
              "icon": {
                "type": "string",
                "enum": [
                  "sparkles",
                  "heart",
                  "shield",
                  "truck"
                ]
              }
            },
            "required": [
              "title",
              "description",
              "icon"
            ],
            "additionalProperties": false
          }
        },
        "location_headline": {
          "type": "string",
          "maxLength": 1500
        },
        "location_headline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "location_subheadline": {
          "type": "string",
          "maxLength": 1500
        },
        "location_subheadline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "address": {
          "type": "string",
          "maxLength": 1500
        },
        "address_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hours": {
          "type": "string",
          "maxLength": 1500
        },
        "hours_en": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_handle": {
          "type": "string",
          "maxLength": 200,
          "description": "Handle, @prefix or profile URL — normalized server-side"
        },
        "logo_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only — uploads are a Studio capability"
        },
        "hero_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only"
        },
        "story_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only"
        }
      },
      "additionalProperties": false
    },
    "merchant_request": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Free-text merchant context. Echoed as heard — never stored, logged or audited."
    }
  },
  "additionalProperties": false
}

get_storefront_design_diffstore:read

READ

Return the EXACT structured diff between the current canonical design and the proposed one: design direction, Brand DNA token values (old/new), homepage sections added/removed/moved/modified with positions and field values, commerce visuals and navigation. Deterministic and complete — every change is an exact value, never prose.

No confirmation token required; all other access and business checks still apply.

get_storefront_design_diff · inputSchema

{
  "type": "object",
  "properties": {
    "requested_direction": {
      "type": "string",
      "enum": [
        "editorial-noir",
        "atelier-sculpted",
        "paper-boutique",
        "frame-eyewear",
        "luminous-editorial",
        "ember-expressive",
        "kinetic-craft",
        "greenery-market"
      ],
      "description": "Design Direction to select (curated registry — no custom directions)"
    },
    "brand_changes": {
      "type": "object",
      "description": "Brand DNA tokens to CHANGE — every key not listed is preserved exactly. Colors are #RRGGBB.",
      "properties": {
        "primary": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "accent": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "background": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "surface": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "text": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "muted": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_background": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_surface": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_text": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "border": {
          "type": "string",
          "pattern": "^(|#[0-9a-fA-F]{6})$",
          "description": "'' derives from the palette"
        },
        "radius": {
          "type": "string",
          "enum": [
            "",
            "sharp",
            "soft",
            "round"
          ]
        },
        "button": {
          "type": "string",
          "enum": [
            "",
            "solid",
            "outline"
          ]
        },
        "card": {
          "type": "string",
          "enum": [
            "",
            "elevated",
            "flat",
            "outlined"
          ]
        },
        "image_ratio": {
          "type": "string",
          "enum": [
            "",
            "square",
            "portrait"
          ]
        },
        "motion": {
          "type": "string",
          "enum": [
            "",
            "none",
            "subtle",
            "expressive"
          ]
        }
      },
      "additionalProperties": false
    },
    "homepage_preset_id": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,64}$",
      "description": "Starting composition from the preset registry (get_storefront_design_context lists them)"
    },
    "homepage": {
      "type": "object",
      "description": "Explicit homepage composition — wins over homepage_preset_id. Only registry section types; order = array order.",
      "properties": {
        "sections": {
          "type": "array",
          "maxItems": 20,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9_-]{1,64}$",
                "description": "Stable unique id inside the page"
              },
              "type": {
                "type": "string",
                "enum": [
                  "hero",
                  "category_showcase",
                  "featured_products",
                  "new_arrivals",
                  "product_collection",
                  "promo_banner",
                  "image_text",
                  "brand_story",
                  "feature_cards",
                  "gallery",
                  "location",
                  "social",
                  "cta",
                  "gift_collection"
                ]
              },
              "visible": {
                "type": "boolean"
              },
              "config": {
                "type": "object",
                "additionalProperties": true,
                "description": "Registry-validated per-section fields (see the section registry in context)"
              }
            },
            "required": [
              "id",
              "type"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "sections"
      ],
      "additionalProperties": false
    },
    "commerce_changes": {
      "type": "object",
      "properties": {
        "card_variant": {
          "type": "string",
          "enum": [
            "classic"
          ]
        }
      },
      "additionalProperties": false
    },
    "navigation_changes": {
      "type": "object",
      "properties": {
        "orders_link": {
          "type": "boolean",
          "description": "Header \"My orders\" link — plan-gated; sub-checkout plans cannot enable it"
        }
      },
      "additionalProperties": false
    },
    "content_changes": {
      "type": "object",
      "description": "Storefront CONTENT patch — whitelisted theme content keys only (hero/story/location/social copy, section headings, feature cards, logo/hero/story image URLs). Images are http(s)/relative URLs only — no uploads (MEDIA_NOT_AVAILABLE). Empty string clears a key. Every value is validated against the canonical theme validator; invalid values fail the proposal explicitly.",
      "properties": {
        "store_name": {
          "type": "string",
          "maxLength": 1500
        },
        "store_name_en": {
          "type": "string",
          "maxLength": 1500
        },
        "footer_tagline": {
          "type": "string",
          "maxLength": 1500
        },
        "footer_tagline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_badge": {
          "type": "string",
          "maxLength": 120
        },
        "hero_badge_en": {
          "type": "string",
          "maxLength": 120
        },
        "hero_title": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "story_title": {
          "type": "string",
          "maxLength": 1500
        },
        "story_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "story_text": {
          "type": "string",
          "maxLength": 1500
        },
        "story_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "about_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "about_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_title": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_text": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "returns_text": {
          "type": "string",
          "maxLength": 1500
        },
        "returns_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_title": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "features_title": {
          "type": "string",
          "maxLength": 1500
        },
        "features_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "features_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "features_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "feature_cards": {
          "type": "array",
          "maxItems": 8,
          "description": "Feature cards (max 8) — title/description pairs with a registry icon. Factual claims must come from the merchant.",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "title_en": {
                "type": "string",
                "maxLength": 120
              },
              "description": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "description_en": {
                "type": "string",
                "maxLength": 500
              },
              "icon": {
                "type": "string",
                "enum": [
                  "sparkles",
                  "heart",
                  "shield",
                  "truck"
                ]
              }
            },
            "required": [
              "title",
              "description",
              "icon"
            ],
            "additionalProperties": false
          }
        },
        "location_headline": {
          "type": "string",
          "maxLength": 1500
        },
        "location_headline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "location_subheadline": {
          "type": "string",
          "maxLength": 1500
        },
        "location_subheadline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "address": {
          "type": "string",
          "maxLength": 1500
        },
        "address_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hours": {
          "type": "string",
          "maxLength": 1500
        },
        "hours_en": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_handle": {
          "type": "string",
          "maxLength": 200,
          "description": "Handle, @prefix or profile URL — normalized server-side"
        },
        "logo_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only — uploads are a Studio capability"
        },
        "hero_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only"
        },
        "story_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only"
        }
      },
      "additionalProperties": false
    },
    "merchant_request": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Free-text merchant context. Echoed as heard — never stored, logged or audited."
    }
  },
  "additionalProperties": false
}

apply_storefront_designstorefront:write

WRITE

Apply a CONFIRMED storefront design proposal through the canonical Storefront authority — the same write path the dashboard uses (validation, contrast guard, plan gates, legacy sync, design_rev compare-and-set). HIGH risk, two-leg confirmation: call WITHOUT confirmation_token to receive CONFIRMATION_REQUIRED + a token bound to this exact intent + proposal_id + base revision; the merchant approves; retry with the token. The proposal is recomputed against live state — a moved design answers DESIGN_STALE with fresh state, a changed proposal answers PROPOSAL_CHANGED. Attributed as AUTOMATION and verified against the persisted row before reporting success.

Requires a confirmation token after explicit user approval.

apply_storefront_design · inputSchema

{
  "type": "object",
  "properties": {
    "requested_direction": {
      "type": "string",
      "enum": [
        "editorial-noir",
        "atelier-sculpted",
        "paper-boutique",
        "frame-eyewear",
        "luminous-editorial",
        "ember-expressive",
        "kinetic-craft",
        "greenery-market"
      ],
      "description": "Design Direction to select (curated registry — no custom directions)"
    },
    "brand_changes": {
      "type": "object",
      "description": "Brand DNA tokens to CHANGE — every key not listed is preserved exactly. Colors are #RRGGBB.",
      "properties": {
        "primary": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "accent": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "background": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "surface": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "text": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "muted": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_background": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_surface": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_text": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "border": {
          "type": "string",
          "pattern": "^(|#[0-9a-fA-F]{6})$",
          "description": "'' derives from the palette"
        },
        "radius": {
          "type": "string",
          "enum": [
            "",
            "sharp",
            "soft",
            "round"
          ]
        },
        "button": {
          "type": "string",
          "enum": [
            "",
            "solid",
            "outline"
          ]
        },
        "card": {
          "type": "string",
          "enum": [
            "",
            "elevated",
            "flat",
            "outlined"
          ]
        },
        "image_ratio": {
          "type": "string",
          "enum": [
            "",
            "square",
            "portrait"
          ]
        },
        "motion": {
          "type": "string",
          "enum": [
            "",
            "none",
            "subtle",
            "expressive"
          ]
        }
      },
      "additionalProperties": false
    },
    "homepage_preset_id": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,64}$",
      "description": "Starting composition from the preset registry (get_storefront_design_context lists them)"
    },
    "homepage": {
      "type": "object",
      "description": "Explicit homepage composition — wins over homepage_preset_id. Only registry section types; order = array order.",
      "properties": {
        "sections": {
          "type": "array",
          "maxItems": 20,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9_-]{1,64}$",
                "description": "Stable unique id inside the page"
              },
              "type": {
                "type": "string",
                "enum": [
                  "hero",
                  "category_showcase",
                  "featured_products",
                  "new_arrivals",
                  "product_collection",
                  "promo_banner",
                  "image_text",
                  "brand_story",
                  "feature_cards",
                  "gallery",
                  "location",
                  "social",
                  "cta",
                  "gift_collection"
                ]
              },
              "visible": {
                "type": "boolean"
              },
              "config": {
                "type": "object",
                "additionalProperties": true,
                "description": "Registry-validated per-section fields (see the section registry in context)"
              }
            },
            "required": [
              "id",
              "type"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "sections"
      ],
      "additionalProperties": false
    },
    "commerce_changes": {
      "type": "object",
      "properties": {
        "card_variant": {
          "type": "string",
          "enum": [
            "classic"
          ]
        }
      },
      "additionalProperties": false
    },
    "navigation_changes": {
      "type": "object",
      "properties": {
        "orders_link": {
          "type": "boolean",
          "description": "Header \"My orders\" link — plan-gated; sub-checkout plans cannot enable it"
        }
      },
      "additionalProperties": false
    },
    "content_changes": {
      "type": "object",
      "description": "Storefront CONTENT patch — whitelisted theme content keys only (hero/story/location/social copy, section headings, feature cards, logo/hero/story image URLs). Images are http(s)/relative URLs only — no uploads (MEDIA_NOT_AVAILABLE). Empty string clears a key. Every value is validated against the canonical theme validator; invalid values fail the proposal explicitly.",
      "properties": {
        "store_name": {
          "type": "string",
          "maxLength": 1500
        },
        "store_name_en": {
          "type": "string",
          "maxLength": 1500
        },
        "footer_tagline": {
          "type": "string",
          "maxLength": 1500
        },
        "footer_tagline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_badge": {
          "type": "string",
          "maxLength": 120
        },
        "hero_badge_en": {
          "type": "string",
          "maxLength": 120
        },
        "hero_title": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "story_title": {
          "type": "string",
          "maxLength": 1500
        },
        "story_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "story_text": {
          "type": "string",
          "maxLength": 1500
        },
        "story_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "about_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "about_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_title": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_text": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "returns_text": {
          "type": "string",
          "maxLength": 1500
        },
        "returns_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_title": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "features_title": {
          "type": "string",
          "maxLength": 1500
        },
        "features_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "features_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "features_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "feature_cards": {
          "type": "array",
          "maxItems": 8,
          "description": "Feature cards (max 8) — title/description pairs with a registry icon. Factual claims must come from the merchant.",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "title_en": {
                "type": "string",
                "maxLength": 120
              },
              "description": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "description_en": {
                "type": "string",
                "maxLength": 500
              },
              "icon": {
                "type": "string",
                "enum": [
                  "sparkles",
                  "heart",
                  "shield",
                  "truck"
                ]
              }
            },
            "required": [
              "title",
              "description",
              "icon"
            ],
            "additionalProperties": false
          }
        },
        "location_headline": {
          "type": "string",
          "maxLength": 1500
        },
        "location_headline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "location_subheadline": {
          "type": "string",
          "maxLength": 1500
        },
        "location_subheadline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "address": {
          "type": "string",
          "maxLength": 1500
        },
        "address_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hours": {
          "type": "string",
          "maxLength": 1500
        },
        "hours_en": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_handle": {
          "type": "string",
          "maxLength": 200,
          "description": "Handle, @prefix or profile URL — normalized server-side"
        },
        "logo_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only — uploads are a Studio capability"
        },
        "hero_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only"
        },
        "story_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only"
        }
      },
      "additionalProperties": false
    },
    "merchant_request": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Free-text merchant context. Echoed as heard — never stored, logged or audited."
    },
    "proposal_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "The sha256 proposal_id from propose_storefront_design"
    },
    "base_design_rev": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000,
      "description": "The design_rev the proposal was built on — refused as DESIGN_STALE if it moved"
    },
    "confirmation_token": {
      "type": "string",
      "format": "uuid",
      "description": "Server-issued single-use confirmation for this exact request"
    }
  },
  "required": [
    "proposal_id",
    "base_design_rev"
  ],
  "additionalProperties": false
}

verify_storefront_designstore:read

READ

Verify a proposal against the PERSISTED storefront (also run automatically after apply): rereads the canonical row and proves direction, every explicitly-requested Brand DNA key, the full homepage composition and commerce/navigation values — reporting matched, missing and unexpected changes plus the current design revision. NOT_APPLIED means the revision never moved.

No confirmation token required; all other access and business checks still apply.

verify_storefront_design · inputSchema

{
  "type": "object",
  "properties": {
    "requested_direction": {
      "type": "string",
      "enum": [
        "editorial-noir",
        "atelier-sculpted",
        "paper-boutique",
        "frame-eyewear",
        "luminous-editorial",
        "ember-expressive",
        "kinetic-craft",
        "greenery-market"
      ],
      "description": "Design Direction to select (curated registry — no custom directions)"
    },
    "brand_changes": {
      "type": "object",
      "description": "Brand DNA tokens to CHANGE — every key not listed is preserved exactly. Colors are #RRGGBB.",
      "properties": {
        "primary": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "accent": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "background": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "surface": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "text": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "muted": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_background": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_surface": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "dark_text": {
          "type": "string",
          "pattern": "^#[0-9a-fA-F]{6}$"
        },
        "border": {
          "type": "string",
          "pattern": "^(|#[0-9a-fA-F]{6})$",
          "description": "'' derives from the palette"
        },
        "radius": {
          "type": "string",
          "enum": [
            "",
            "sharp",
            "soft",
            "round"
          ]
        },
        "button": {
          "type": "string",
          "enum": [
            "",
            "solid",
            "outline"
          ]
        },
        "card": {
          "type": "string",
          "enum": [
            "",
            "elevated",
            "flat",
            "outlined"
          ]
        },
        "image_ratio": {
          "type": "string",
          "enum": [
            "",
            "square",
            "portrait"
          ]
        },
        "motion": {
          "type": "string",
          "enum": [
            "",
            "none",
            "subtle",
            "expressive"
          ]
        }
      },
      "additionalProperties": false
    },
    "homepage_preset_id": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,64}$",
      "description": "Starting composition from the preset registry (get_storefront_design_context lists them)"
    },
    "homepage": {
      "type": "object",
      "description": "Explicit homepage composition — wins over homepage_preset_id. Only registry section types; order = array order.",
      "properties": {
        "sections": {
          "type": "array",
          "maxItems": 20,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[a-z0-9_-]{1,64}$",
                "description": "Stable unique id inside the page"
              },
              "type": {
                "type": "string",
                "enum": [
                  "hero",
                  "category_showcase",
                  "featured_products",
                  "new_arrivals",
                  "product_collection",
                  "promo_banner",
                  "image_text",
                  "brand_story",
                  "feature_cards",
                  "gallery",
                  "location",
                  "social",
                  "cta",
                  "gift_collection"
                ]
              },
              "visible": {
                "type": "boolean"
              },
              "config": {
                "type": "object",
                "additionalProperties": true,
                "description": "Registry-validated per-section fields (see the section registry in context)"
              }
            },
            "required": [
              "id",
              "type"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "sections"
      ],
      "additionalProperties": false
    },
    "commerce_changes": {
      "type": "object",
      "properties": {
        "card_variant": {
          "type": "string",
          "enum": [
            "classic"
          ]
        }
      },
      "additionalProperties": false
    },
    "navigation_changes": {
      "type": "object",
      "properties": {
        "orders_link": {
          "type": "boolean",
          "description": "Header \"My orders\" link — plan-gated; sub-checkout plans cannot enable it"
        }
      },
      "additionalProperties": false
    },
    "content_changes": {
      "type": "object",
      "description": "Storefront CONTENT patch — whitelisted theme content keys only (hero/story/location/social copy, section headings, feature cards, logo/hero/story image URLs). Images are http(s)/relative URLs only — no uploads (MEDIA_NOT_AVAILABLE). Empty string clears a key. Every value is validated against the canonical theme validator; invalid values fail the proposal explicitly.",
      "properties": {
        "store_name": {
          "type": "string",
          "maxLength": 1500
        },
        "store_name_en": {
          "type": "string",
          "maxLength": 1500
        },
        "footer_tagline": {
          "type": "string",
          "maxLength": 1500
        },
        "footer_tagline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_badge": {
          "type": "string",
          "maxLength": 120
        },
        "hero_badge_en": {
          "type": "string",
          "maxLength": 120
        },
        "hero_title": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "hero_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "story_title": {
          "type": "string",
          "maxLength": 1500
        },
        "story_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "story_text": {
          "type": "string",
          "maxLength": 1500
        },
        "story_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "about_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "about_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_title": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_text": {
          "type": "string",
          "maxLength": 1500
        },
        "mission_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "returns_text": {
          "type": "string",
          "maxLength": 1500
        },
        "returns_text_en": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_title": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "bestsellers_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "features_title": {
          "type": "string",
          "maxLength": 1500
        },
        "features_title_en": {
          "type": "string",
          "maxLength": 1500
        },
        "features_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "features_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "feature_cards": {
          "type": "array",
          "maxItems": 8,
          "description": "Feature cards (max 8) — title/description pairs with a registry icon. Factual claims must come from the merchant.",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "title_en": {
                "type": "string",
                "maxLength": 120
              },
              "description": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "description_en": {
                "type": "string",
                "maxLength": 500
              },
              "icon": {
                "type": "string",
                "enum": [
                  "sparkles",
                  "heart",
                  "shield",
                  "truck"
                ]
              }
            },
            "required": [
              "title",
              "description",
              "icon"
            ],
            "additionalProperties": false
          }
        },
        "location_headline": {
          "type": "string",
          "maxLength": 1500
        },
        "location_headline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "location_subheadline": {
          "type": "string",
          "maxLength": 1500
        },
        "location_subheadline_en": {
          "type": "string",
          "maxLength": 1500
        },
        "address": {
          "type": "string",
          "maxLength": 1500
        },
        "address_en": {
          "type": "string",
          "maxLength": 1500
        },
        "hours": {
          "type": "string",
          "maxLength": 1500
        },
        "hours_en": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_subtitle": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_subtitle_en": {
          "type": "string",
          "maxLength": 1500
        },
        "instagram_handle": {
          "type": "string",
          "maxLength": 200,
          "description": "Handle, @prefix or profile URL — normalized server-side"
        },
        "logo_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only — uploads are a Studio capability"
        },
        "hero_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only"
        },
        "story_image": {
          "type": "string",
          "maxLength": 4096,
          "description": "URL only"
        }
      },
      "additionalProperties": false
    },
    "merchant_request": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Free-text merchant context. Echoed as heard — never stored, logged or audited."
    },
    "proposal_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "base_design_rev": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000
    }
  },
  "required": [
    "proposal_id",
    "base_design_rev"
  ],
  "additionalProperties": false
}

preview_bulk_inventoryinventory:read

READ

Preview a bulk inventory operation (receive or adjust, up to 25 records): every record resolved against the merchant’s own stores with its authoritative before-quantity, plus a preview hash. Execute requires this exact hash — it proves the underlying state has not drifted since the preview.

No confirmation token required; all other access and business checks still apply.

preview_bulk_inventory · inputSchema

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "RECEIVE",
        "ADJUST"
      ]
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 25,
      "items": {
        "type": "object",
        "properties": {
          "record_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Your stable per-record correlation id — unique within the batch; also keys per-record idempotency"
          },
          "item_type": {
            "type": "string",
            "enum": [
              "PRODUCT",
              "VARIANT",
              "INGREDIENT"
            ]
          },
          "item_id": {
            "type": "string",
            "format": "uuid"
          },
          "quantity": {
            "type": "number",
            "minimum": -100000000,
            "maximum": 100000000,
            "description": "RECEIVE: positive (min 0.000001); ADJUST: signed non-zero"
          },
          "unit_code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 10
          },
          "unit_cost": {
            "type": "number",
            "minimum": 0,
            "description": "RECEIVE only"
          },
          "kind": {
            "type": "string",
            "enum": [
              "ADJUSTMENT",
              "DAMAGE",
              "LOSS"
            ]
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300,
            "description": "Required for every ADJUST record"
          }
        },
        "required": [
          "record_ref",
          "item_type",
          "item_id",
          "quantity"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "operation",
    "items"
  ],
  "additionalProperties": false
}

apply_bulk_inventoryinventory:write

WRITE

Execute a previewed bulk inventory operation through the canonical inventory authorities (two-leg server confirmation first). Per record: exact-once via the operation id + your record_ref, continue-on-failure with a per-record result, and an authoritative reread per applied record. No cross-record rollback — a failed record never blocks the others.

Requires a confirmation token after explicit user approval.

apply_bulk_inventory · inputSchema

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "RECEIVE",
        "ADJUST"
      ]
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 25,
      "items": {
        "type": "object",
        "properties": {
          "record_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "item_type": {
            "type": "string",
            "enum": [
              "PRODUCT",
              "VARIANT",
              "INGREDIENT"
            ]
          },
          "item_id": {
            "type": "string",
            "format": "uuid"
          },
          "quantity": {
            "type": "number",
            "minimum": -100000000,
            "maximum": 100000000,
            "description": "RECEIVE: positive (min 0.000001); ADJUST: signed non-zero"
          },
          "unit_code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 10
          },
          "unit_cost": {
            "type": "number",
            "minimum": 0,
            "description": "RECEIVE only"
          },
          "kind": {
            "type": "string",
            "enum": [
              "ADJUSTMENT",
              "DAMAGE",
              "LOSS"
            ]
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300,
            "description": "Required for every ADJUST record"
          }
        },
        "required": [
          "record_ref",
          "item_type",
          "item_id",
          "quantity"
        ],
        "additionalProperties": false
      }
    },
    "operation_id": {
      "type": "string",
      "format": "uuid",
      "description": "Your stable id for this whole bulk operation — replaying it yields per-record REPLAYED, never a re-apply"
    },
    "preview_hash": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "The sha256 preview_hash from preview_bulk_inventory — refused as PREVIEW_STALE if state drifted"
    },
    "confirmation_token": {
      "type": "string",
      "format": "uuid",
      "description": "Server-issued single-use confirmation for this exact request"
    }
  },
  "required": [
    "operation",
    "items",
    "operation_id",
    "preview_hash"
  ],
  "additionalProperties": false
}

get_store_builder_contextstore:read

READ

Understand a store the way a store architect would before building it: business type, plan capabilities, catalog shape (available/featured counts, category names, sample products), the authoritative current design and contrast report, which storefront content keys are set, profile contact channels (WhatsApp/phone/email — dashboard-only for writes), effective feature states, and a DETERMINISTIC build recommendation (direction, Brand DNA palette only when no colors exist, registry-preset homepage composition adjusted to real data, minimal registry-derived headings, missing-content questions, blocked capabilities with the honest dashboard path). Returns a ready-to-pass proposal intent for propose_storefront_design. Read-only; mutations happen only through the confirmed E7s apply tool.

No confirmation token required; all other access and business checks still apply.

get_store_builder_context · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_store_setup_statusstore:read

READ

Answer "اعمل المتجر بتاعي / إيه اللي ناقص؟" for the whole merchant setup: per-capability readiness across identity, brand, design, homepage, navigation, catalog, catalog configuration, contacts, social, store information, orders/checkout/payments/fulfillment, marketing, inventory, CRM, restaurant (menu/floor plan/kitchen), KDS, branches and staff — each in exactly one honest status (READY / MISSING_INPUT / AUTO_CONFIGURABLE / CONFIRMATION_REQUIRED / PLAN_LOCKED / DASHBOARD_ONLY / NOT_SUPPORTED / NOT_APPLICABLE), with the readiness ladder (NOT_READY → NEEDS_MERCHANT_INPUT → READY_FOR_PUBLICATION → READY_FOR_ORDERS), a prioritized question list (only what the server cannot know), a deterministic setup plan whose every executable action names its real existing authority tool, blocked entries with dashboard/upgrade paths, and a final readiness report. Includes the deterministic design build recommendation with a ready-to-pass intent for propose_storefront_design. Read-only; mutations happen only through the closed confirmed authorities.

No confirmation token required; all other access and business checks still apply.

get_store_setup_status · inputSchema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

COMPLETE YOUR INTEGRATION

Public APIREST endpoints, scopes and request examples.WebhooksEvents, payloads and signature verification.n8n nodeAction and trigger nodes in one workflow.