> ## 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.

# Read Shopify setup

> Read native Shopify plugin availability, linked stores, existing assistants and central Tools assignments. Requires workspace owner/admin and both integrations:read and assistants:read.



## OpenAPI

````yaml GET /shopify/setup
openapi: 3.1.0
info:
  title: Famulor API
  version: 1.0.0
  description: >-
    REST API for Famulor. Authenticate with an API key (`fam_...`, created under
    **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`) as a
    Bearer token.


    Every response uses a consistent envelope: `{ "data": ... , "meta": { ... }
    }` on success and `{ "error": { "code", "message" } }` on failure. List
    endpoints paginate with `?limit=` (default 50, max 200) and `?offset=`;
    `meta.pagination.total` carries the total match count.


    REST operations require API Access through the workspace plan or a recurring
    add-on. Without it, regular operations return `403 api_access_required`. The
    invoice-payment and billing-portal operations remain available with a valid
    `billing:write` credential after a failed plan payment so an authorized
    owner, admin, or billing member can recover billing.


    The same customer-facing capabilities are available as MCP tools at
    `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using
    the same credentials, scopes, and workspace access. MCP availability is
    controlled separately by Connect AI / MCP, not by API Access.
servers:
  - url: https://app.famulor.io/api/v1
    description: Hosted platform.
  - url: https://{domain}/api/v1
    description: White-label tenant domain — same paths, tenant branding.
    variables:
      domain:
        default: app.famulor.io
        description: Your white-label tenant domain.
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Self-inspection of the calling credential.
  - name: Migrations
    description: Preview and import data from supported legacy platforms.
  - name: Assistants
    description: Create and manage voice assistants.
  - name: Tools
    description: >-
      Reusable tools (HTTP APIs, external MCP servers and actions of connected
      apps) assistants can call mid-conversation.
  - name: Voices
    description: Browse the text-to-speech voice library.
  - name: Calls
    description: Start outbound calls and read call history, transcripts and recordings.
  - name: History
    description: Unified conversation history across calls, messaging and assistant emails.
  - name: Campaigns
    description: Outbound calling campaigns with a compliant power dialer.
  - name: Leads
    description: Manage Audience contacts across campaigns, channels and Call QA metrics.
  - name: Segments
    description: >-
      Saved, dynamic lead filters — reusable audience definitions used for
      Audience search and campaign lead assignment.
  - name: Suppression
    description: Cross-channel marketing opt-outs and active workspace suppression records.
  - name: Callbacks
    description: >-
      Scheduled callbacks booked by the Schedule callback tool across voice,
      chat, and email.
  - name: Phone Numbers
    description: Marketplace numbers and customer-provided numbers.
  - name: Famulor Loop
    description: >-
      Personal business-phone access, directory, presence, devices, and Loop
      call recents.
  - name: SIP Trunks
    description: Bring your own SIP provider and numbers.
  - name: Carrier Connections
    description: Connect a supported carrier account and import its existing phone numbers.
  - name: Knowledge Bases
    description: RAG knowledge bases and documents for assistants.
  - name: Settings
    description: Workspace-level settings such as caller-memory defaults.
  - name: Billing
    description: Balance and transaction ledger of the API key's workspace.
  - name: Automations
    description: >-
      Native workspace automations — list, create, update, trigger. Requires
      Automations in the workspace plan.
  - name: Milian Missions
    description: Recurring jobs that Milian runs unattended on schedule.
  - name: Integrations
    description: >-
      Calendar integrations (Cal.com, Calendly, Acuity Scheduling, Google
      Calendar, Outlook, native booking engine). Assign them to assistants to
      provide availability and booking tools, plus provider-supported
      appointment lookup, cancellation, and rescheduling.
  - name: Bookings
    description: >-
      Native booking engine — event types with weekly availability, public
      booking pages at /book/{workspace}/{slug}, and the bookings they produce.
  - name: Dashboards
    description: >-
      Custom analytics dashboards, reusable widgets, and tenant-scoped
      performance analytics. Requires Custom dashboards in the workspace plan.
  - name: Catalog
    description: >-
      Read-only platform catalogs — available models, supported assistant
      languages, and prompt templates.
  - name: Simulations
    description: Assistant simulation tests (plan-gated).
  - name: Versions
    description: Assistant configuration version history.
  - name: Caller IDs
    description: Outbound caller ID verification.
  - name: Widgets
    description: Web widget connectors.
  - name: Messaging
    description: >-
      Telegram, Slack, and Messenger text bots linked to assistants (Chat SDK).
      Includes conversation delay, inactivity end, and conversation-ended
      webhooks.
  - name: QA
    description: Cohort AI Quality Assurance runs over call transcripts.
  - name: White Label
    description: >-
      Manage white-label customer accounts, defaults, credit transfers and
      customer plan offers. Each endpoint documents its required scope and
      workspace eligibility.
  - name: API Keys
    description: >-
      Self-service API keys for the calling workspace or a same-brand workspace
      where the credential's user is owner/admin. A key can only mint further
      keys with a scope subset of its own.
  - name: Workspaces
    description: >-
      List visible workspaces, create an additional workspace for the key owner,
      and mint a dedicated credential for a selected owner/admin workspace.
  - name: SMS
    description: Outbound SMS from workspace phone numbers.
  - name: Milian
    description: >-
      Ask Milian, the AI co-worker in your workspace, and start voice sessions
      with it.
  - name: Translation
    description: >-
      Live translation sessions that interpret a conversation between two
      languages.
  - name: Shopify
    description: Native Shopify app store connections, assistant tools and activity.
  - name: Avatars
    description: Private custom avatars and widget avatar selection.
  - name: Webhook Subscriptions
    description: >-
      Signed workspace event subscriptions, independent of existing
      destinations.
paths:
  /shopify/setup:
    get:
      tags:
        - Shopify
      summary: Read Shopify setup
      description: >-
        Read native Shopify plugin availability, linked stores, existing
        assistants and central Tools assignments. Requires workspace owner/admin
        and both integrations:read and assistants:read.
      operationId: getShopifySetup
      parameters:
        - name: installation_id
          description: Select a linked store.
          schema:
            type: string
            format: uuid
          in: query
        - name: assistant_id
          description: Filter existing assignments by assistant.
          schema:
            type: string
            format: uuid
          in: query
      responses:
        '200':
          description: List Shopify assistant tools.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ShopifySetup'
                required:
                  - data
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ShopifySetup:
      type: object
      properties:
        available:
          type: boolean
          description: Whether the native plugin is available for this workspace.
        canManage:
          type: boolean
          description: Whether the current actor can manage this connection.
        installations:
          type: array
          description: Linked stores.
          items:
            $ref: '#/components/schemas/ShopifyInstallation'
        assistants:
          type: array
          description: Existing workspace assistants.
          items:
            type: object
            properties:
              id:
                type: string
                description: Assistant ID.
                format: uuid
              name:
                type: string
                description: Assistant name.
              mode:
                type: string
                description: Assistant mode.
            required:
              - id
              - name
              - mode
        actions:
          type: array
          description: Catalog actions with connection-specific availability.
          items:
            allOf:
              - $ref: '#/components/schemas/ShopifyAction'
              - type: object
                properties:
                  available:
                    type: boolean
                    description: >-
                      Whether merchant capability and store permission
                      prerequisites are met.
                required: []
        capabilities:
          $ref: '#/components/schemas/ShopifyCapabilities'
        toolAssignments:
          type: array
          description: Existing central Tools assignments.
          items:
            $ref: '#/components/schemas/ShopifyAssistantTool'
        checks:
          type: array
          description: Workspace and connection prerequisite checks.
          items:
            type: object
            properties:
              id:
                type: string
                description: Check ID.
              label:
                type: string
                description: Check label.
              status:
                type: string
                description: Prerequisite status.
              detail:
                type: string
                description: Actionable explanation.
            required:
              - id
              - label
              - status
              - detail
        installUrl:
          type:
            - string
            - 'null'
          description: Installation link if provided.
      required:
        - available
        - canManage
        - installations
        - assistants
        - actions
        - toolAssignments
        - checks
        - installUrl
    ShopifyInstallation:
      type: object
      properties:
        id:
          type: string
          description: Linked Shopify store ID
          format: uuid
          readOnly: true
        shop_domain:
          type: string
          description: Canonical store domain
          readOnly: true
        status:
          type: string
          description: Connection status
          enum:
            - installed
            - disconnected
            - uninstalled
          readOnly: true
        scopes:
          type: array
          description: Permissions approved in Shopify
          items:
            type: string
          readOnly: true
        created_at:
          type: string
          description: Connection created time
          format: date-time
          readOnly: true
        updated_at:
          type: string
          description: Last update time
          format: date-time
          readOnly: true
      required:
        - id
        - shop_domain
        - status
        - scopes
        - created_at
        - updated_at
    ShopifyAction:
      type: object
      properties:
        id:
          type: string
          description: Native assistant action
          enum:
            - lookup_order
            - search_products
            - get_product_inventory
            - get_shop_policies
            - request_cancellation
            - request_refund
            - request_address_change
            - create_support_ticket
            - get_shop_context
            - get_product
            - get_customer_context
            - get_return_eligibility
            - start_customer_verification
            - prepare_draft_order
            - prepare_order_cancellation
            - prepare_address_change
            - prepare_return
            - prepare_draft_invoice
            - execute_shopify_proposal
            - get_shopify_proposal
            - start_secure_shopify_request
        title:
          type: string
          description: Action label
        description:
          type: string
          description: Action behavior
        requiredScopes:
          type: array
          description: Required store permissions
          items:
            type: string
        requiresCustomerVerification:
          type: boolean
          description: Whether the caller must verify the exact order
        requiresMerchantApproval:
          type: boolean
          description: Whether the action queues a merchant-review request
        parameters:
          type: array
          description: Action inputs
          items:
            type: object
            properties:
              name:
                type: string
                description: Input name
              type:
                type: string
                description: Input type
                enum:
                  - string
              description:
                type: string
                description: Input usage
              required:
                type: boolean
                description: Whether the input is mandatory
            required:
              - name
              - type
              - description
              - required
        capability:
          type: string
          description: Merchant capability required for managed actions.
          enum:
            - voice_checkout
            - send_draft_invoice
            - cancel_orders
            - update_shipping_address
            - request_returns
            - secure_customer_support
      required:
        - id
        - title
        - description
        - requiredScopes
        - requiresCustomerVerification
        - requiresMerchantApproval
        - parameters
    ShopifyCapabilities:
      type: object
      properties:
        enabled:
          type: array
          description: Merchant-enabled capability IDs.
          items:
            type: string
            enum:
              - voice_checkout
              - send_draft_invoice
              - cancel_orders
              - update_shipping_address
              - request_returns
              - secure_customer_support
        config:
          $ref: '#/components/schemas/ShopifyCapabilityConfig'
        requiredScopes:
          type: object
          description: Store permissions required for each capability.
          additionalProperties:
            type: array
            items:
              type: string
        missingScopes:
          type: array
          description: Missing store permissions for enabled capabilities.
          items:
            type: string
        version:
          type: integer
          minimum: 0
          description: >-
            Settings version for optimistic concurrency. Send as
            expected_version on updates.
        available:
          type: object
          readOnly: true
          description: >-
            Current availability of optional capabilities. A missing or false
            entry means it cannot be enabled. Existing settings can still be
            turned off or preserved when saving other permissions.
          properties:
            secure_customer_support:
              type: boolean
              description: >-
                Whether optional private support for customers with an existing
                order can currently be enabled. Order verification remains
                required, including for checkout.
      required:
        - enabled
        - config
        - requiredScopes
        - missingScopes
        - version
    ShopifyAssistantTool:
      type: object
      properties:
        id:
          type: string
          description: Tool assignment ID
          format: uuid
        assistant_id:
          type: string
          description: Assistant ID
          format: uuid
        installation_id:
          type: string
          description: Linked store ID
          format: uuid
        action:
          type: string
          description: Native assistant action
          enum:
            - lookup_order
            - search_products
            - get_product_inventory
            - get_shop_policies
            - request_cancellation
            - request_refund
            - request_address_change
        tool_id:
          type: string
          description: Assistant tool ID
          format: uuid
        automation_id:
          type: string
          description: Backing automation ID
          format: uuid
        tool_name:
          type: string
          description: Assistant tool name
        active:
          type: boolean
          description: Whether the tool is enabled
      required:
        - id
        - assistant_id
        - installation_id
        - action
        - tool_id
        - automation_id
        - tool_name
        - active
    ErrorEnvelope:
      type: object
      description: Error envelope returned by every /api/v1 endpoint on failure.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - forbidden
                - api_access_required
                - not_found
                - invalid_request
                - rate_limited
                - conflict
                - telephony_configuration_error
                - telephony_unavailable
                - destination_forbidden
                - internal_error
                - service_unavailable
                - verification_address_required
                - bundle_address_missing
              description: >-
                Stable, machine-readable error code. `service_unavailable` is
                returned by POST /bookings and GET
                /booking-event-types/{id}/slots specifically when the
                availability engine could not be reached (see
                AvailabilityOrProtectionUnavailable).
                `verification_address_required` and `bundle_address_missing` are
                returned by POST /phone-numbers when the verification behind the
                number has no address (see the operation description).
            message:
              type: string
              description: Human-readable description of the error.
            reason:
              type: string
              description: >-
                Optional, more specific and stable reason for this error, for
                example `plan_required`, `read_only_role` or `missing_scope`.
                Branch on `code` first: `reason` is only present on some errors,
                and new values may be added. Campaign operations use
                `attestation_required` (400, `compliance_attestation` missing on
                launch), `launch_required` (400, a sequence campaign was never
                launched; launch it or start it with `compliance_attestation`),
                `sequence_changed` (409, the sequence changed after
                `sequence_hash` was taken), `campaign_sequences_unavailable`
                (403, the plan does not include Campaign sequences),
                `campaign_extension_unavailable` (503 `service_unavailable`, the
                campaign feature is not available yet) and `analytics_timeout`
                (504 `service_unavailable`, the campaign analytics took too
                long; choose a shorter period).
            hint:
              type: string
              description: >-
                Optional recovery advice that is safe to show to the end user,
                for example which settings page to open.
    ShopifyCapabilityConfig:
      type: object
      properties:
        allowBackorders:
          type: boolean
          description: Allow variants whose store policy permits backorders.
          default: false
        cancellation:
          type: object
          properties:
            unfulfilledOnly:
              type: boolean
              description: Restrict cancellation to unfulfilled orders.
            maximumAgeHours:
              type: integer
              description: Maximum order age in hours.
              minimum: 1
              maximum: 720
            excludedTags:
              type: array
              description: Order tags that prevent cancellation.
              items:
                type: string
                minLength: 1
                maxLength: 100
              maxItems: 30
            refundMode:
              type: string
              description: No automatic refunds are supported.
              enum:
                - none
            restock:
              type: boolean
              description: Restock cancelled items.
            notifyCustomer:
              type: boolean
              description: Send the store cancellation notification.
          required:
            - unfulfilledOnly
            - maximumAgeHours
            - excludedTags
            - refundMode
            - restock
            - notifyCustomer
        websiteWidgetNames:
          type: object
          description: >-
            Explicit opt-in for publishing eligible widget names as public
            Shopify storefront data. Disabled by default. Setting enabled to
            false immediately stops named selections from working and schedules
            removal of published choices. Preserve the latest other capability
            settings when submitting an update.
          required:
            - enabled
          properties:
            enabled:
              type: boolean
              default: false
              description: >-
                Whether public named-widget publication is enabled. Explicit
                widget synchronization enables this setting; background
                reconciliation never enables it.
      required: []
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: invalid_request
              message: '"to_number" is required (E.164 format, e.g. +4930123456).'
    Unauthorized:
      description: Missing, invalid, expired or revoked API key / access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: unauthorized
              message: Invalid API key.
    Forbidden:
      description: >-
        The credential lacks the required scope or role, or the workspace does
        not have the required capability.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            scopeDenied:
              summary: Required scope is missing
              value:
                error:
                  code: forbidden
                  message: >-
                    This API key is missing the required scope
                    "assistants:write".
            apiAccessRequired:
              summary: API Access is not available
              value:
                error:
                  code: api_access_required
                  message: >-
                    API Access is not available for this workspace. Review
                    Settings → Plan.
    RateLimited:
      description: Too many requests. Retry after the indicated delay.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: rate_limited
              message: Too many requests. Retry after the indicated delay.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        API key (`fam_...`, created under **Settings → API Keys**) or an OAuth
        2.0 access token (`fam_at_...`). REST operations also require API Access
        for the credential's workspace. Keys can be restricted to scopes such as
        `assistants:read`, `calls:write`, `campaigns:write`, `automations:read`,
        `dashboards:read`, `dashboards:write`, `leads:write`, `segments:write`,
        `loop:read`, `loop:write`, `phone_numbers:write`, `sip_trunks:write`,
        `knowledge:write`, `voices:read`, `billing:read`, `billing:write`,
        `settings:write`, `platform:read`, `platform:write`; a `*:write` scope
        implies the matching `*:read`. Automation and dashboard endpoints also
        accept the legacy `calls:*` scope. Keys without scope restrictions have
        full access within the workspace's available capabilities.

````

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