> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Famulor Shopify app

> Connect an existing Famulor workspace once and use voice support tools inside Shopify Admin.

The **Famulor AI Agent** app connects one Shopify store to an existing Famulor workspace. The store owner installs the app, opens it in Shopify Admin and approves the workspace link. You do not paste API secrets or enter a store domain.

The Shopify app has no additional app fee. Your existing Famulor subscription and usage charges apply. An existing Famulor account is required.

## Connect your workspace

1. Open **Famulor AI Agent** in Shopify Admin as the store owner.
2. Choose **Connect Famulor workspace**. Sign in to Famulor in the new tab.
3. Select a workspace where you are an owner or admin and choose **Connect store**.
4. Return to Shopify Admin and choose **Refresh**.

The connection link expires after five minutes and can be used once. Start again from Shopify Admin if it expires. Only the store owner can open the app's connected workspace data.

## Add assistant tools

Open **Famulor Tools** from Shopify Admin. Configure the native connection and assign store tasks through the existing Tools and Assistant settings. The assistant can search current products, check availability, read policies and look up order status after exact customer verification.

The **request** tools for cancellation, refund and address changes record merchant-review requests. These request tools do not modify Shopify orders. Managed actions are separate and subject to the prerequisites below.

## Review activity

**Store activity** shows actions and conversations attributed to this connected store. It does not expose another store's or workspace's conversations. Expand a conversation to read its transcript and use an available recording.

Manage linked stores in Famulor under **Automations → Connections → Shopify app connections**. Disconnecting prevents assistant tools from accessing this store. Uninstall the app in Shopify to revoke Shopify access.

## API, MCP, CLI and SDK

Initial linking requires the store owner's approval in Shopify Admin. After linking, owner/admin credentials can manage the store programmatically.

| Task | REST API | MCP tool | CLI command |
| - | - | - | - |
| List stores | `GET /api/v1/shopify/installations` | `list_shopify_installations` | `famulor list-shopify-installations` |
| Action catalog | `GET /api/v1/shopify/actions` | `list_shopify_actions` | `famulor list-shopify-actions` |
| Add assistant tools | `POST /api/v1/shopify/installations/{id}/tools` | `provision_shopify_assistant_tools` | `famulor provision-shopify-assistant-tools STORE_ID --assistant-id ASSISTANT_ID --actions lookup_order` |
| Store history | `GET /api/v1/shopify/installations/{id}/history` | `list_shopify_history` | `famulor list-shopify-history STORE_ID` |
| Support requests | `GET /api/v1/shopify/installations/{id}/requests` | `list_shopify_support_requests` | `famulor list-shopify-support-requests STORE_ID` |
| Record handling | `PATCH /api/v1/shopify/installations/{id}/requests` | `resolve_shopify_support_request` | `famulor resolve-shopify-support-request STORE_ID --request-id REQUEST_ID --status completed` |
| Conversation | `GET /api/v1/shopify/installations/{id}/calls/{callId}` | `get_shopify_call` | `famulor get-shopify-call STORE_ID CALL_ID` |
| Privacy reports | `GET /api/v1/shopify/installations/{id}/privacy-exports` | `list_shopify_privacy_exports` | `famulor list-shopify-privacy-exports STORE_ID` |
| Privacy report | `GET /api/v1/shopify/installations/{id}/privacy-exports/{exportId}` | `get_shopify_privacy_export` | `famulor get-shopify-privacy-export STORE_ID EXPORT_ID` |
| Disconnect | `DELETE /api/v1/shopify/installations/{id}` | `disconnect_shopify_installation` | `famulor disconnect-shopify-installation STORE_ID` |

Read access uses `integrations:read`. Assistant setup also requires `assistants:write`, and store history requires `calls:read`. Store changes use `integrations:write`.

```ts theme={null}
import { Famulor } from "famulor-sdk";
const famulor = new Famulor({ apiKey: process.env.FAMULOR_API_KEY! });
const stores = await famulor.shopify.installations();
const actions = await famulor.shopify.actions();
const activity = await famulor.shopify.history(stores.data[0].id);
```

The separate [own-app automation connector](/automations/shopify) remains available for your own Shopify app credentials. The native app's reviewed assistant tools and the own-app connector have separate connections and capabilities.

## Native Shopify plugin (Beta)

Enable Beta features in your workspace. Open **Tools → Agent Connectors** or **Automations → Connections**, select **Shopify AI Agent App (Beta)** and connect the same store. Create or choose an assistant in the existing **Assistants** interface, then select and assign native Shopify tools through central **Tools**. Knowledge, SMS, transfers, callbacks, phone routing and campaigns use their existing Famulor settings.

Products, variants, prices and stock are read live from Shopify; Famulor does not import a product catalog. Prices and stock are snapshots, and checkout calculates final totals. An exact order reference, matching customer email and shipping postcode are required for private order data; caller ID alone is insufficient.

Merchant-review cancellation, refund and address-change requests remain separate from managed Shopify writes. Managed draft orders, invoice emails, cancellations, shipping-address changes and returns require merchant opt-in, store permissions and their supported phone runtime. Existing customer/order writes additionally require private verification and explicit caller confirmation bound to the prepared action. Missing prerequisites block execution. Cancellation does not automatically refund money; a draft order does not charge a customer. Returns depend on current fulfillments and merchant policy, and exchanges may require merchant follow-up. Recovery audiences, subscription access and incremental revenue are not implied by connecting the plugin.

| REST API | MCP | CLI |
| - | - | - |
| `GET /api/v1/shopify/setup` | `get_shopify_setup` | `famulor get-shopify-setup` |
| `PATCH /api/v1/shopify/installations/{id}/capabilities` | `update_shopify_capabilities` | `famulor update-shopify-capabilities STORE_ID --enabled-capabilities voice_checkout --expected-version VERSION` |

```ts theme={null}
const setup = await famulor.shopify.setup();
await famulor.shopify.updateCapabilities(storeId, { enabled_capabilities: ["voice_checkout"], expected_version: setup.data.capabilities!.version });
```

## External phone audiences (Beta)

In the existing campaign Settings, choose an eligible Shopify or Klaviyo connection and a live source segment. Local-lead campaigns retain their existing behavior. Shopify supports selected segments, including merchant-defined VIP segments, win-back, replenishment, abandoned checkout and the supported failed-payment scenario. Klaviyo currently supports selected segments only. Select the replenishment product from the live product picker. Win-back and replenishment need access to older orders. Failed payment means a supported unpaid, uncancelled, non-test order with complete failed transaction evidence and no subsequent successful/pending payment or newer order; subscription events and unsaved checkouts are not included.

Phone calls only; set follow-up to Off. Before each attempt, Famulor checks current segment membership, scenario eligibility, phone and an explicit positive voice-marketing grant. Email/SMS subscription, caller ID and absence from a suppression list do not establish voice permission. Missing proof excludes the recipient. Calling windows, suppression, retries and capacity still apply. Connection and audience settings cannot change once source execution starts.

Map an authoritative source JSON record using the permission namespace and key (namespace is required for Shopify). The record must contain the exact current `subject_ref` and `phone`, `channel: "voice"`, `purpose: "marketing"`, `granted: true`, `revoked: false`, a non-future `granted_at`, an `evidence_ref` and a current `source_revision`. Famulor stores operational references and execution state, not a customer/order/catalog replica.

## Associated net payments

Refresh associated payments in the existing Shopify app activity surface. Famulor reads fresh payment/refund/cancellation state only for stored call-linked order/draft references. Converted drafts resolve to their Shopify order; each order counts once, allocated to the earliest store call association with call ID as the tie-break. Campaign filters apply after this store-wide allocation. Exact decimal totals are grouped by shop currency without conversion. The observation time, refunds, cancellations and incomplete reads are disclosed. Missing references, unavailable access and bounded/older history are never counted as zero revenue. This is association, not incremental revenue or a causal sales claim.

| REST | MCP | CLI |
| - | - | - |
| `GET /api/v1/shopify/installations/{id}/revenue` | `get_shopify_associated_revenue` | `famulor get-shopify-associated-revenue STORE_ID` |

```ts theme={null}
const payments = await famulor.shopify.associatedRevenue(storeId);
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.