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

# Configure Shopify capabilities

> Set the complete merchant-enabled capability set. Missing store permissions still block execution. Customer verification and explicit confirmed intent remain required for managed writes. No automatic refunds. Requires workspace owner/admin and integrations:write. Secure support across channels enables a private customer page; order verification and separate confirmation remain required. Private details stay on that page. Website widget name publication is a separate optional configuration, disabled by default. To turn it off, set capability_config.websiteWidgetNames.enabled to false while preserving the latest enabled capabilities and other configuration. Named selections stop working immediately; existing published choices are removed asynchronously. App-owned widget-name publication does not require extra Shopify access scopes.



## OpenAPI

````yaml PATCH /shopify/installations/{id}/capabilities
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/installations/{id}/capabilities:
    patch:
      tags:
        - Shopify
      summary: Configure Shopify capabilities
      description: >-
        Set the complete merchant-enabled capability set. Missing store
        permissions still block execution. Customer verification and explicit
        confirmed intent remain required for managed writes. No automatic
        refunds. Requires workspace owner/admin and integrations:write. Secure
        support across channels enables a private customer page; order
        verification and separate confirmation remain required. Private details
        stay on that page. Website widget name publication is a separate
        optional configuration, disabled by default. To turn it off, set
        capability_config.websiteWidgetNames.enabled to false while preserving
        the latest enabled capabilities and other configuration. Named
        selections stop working immediately; existing published choices are
        removed asynchronously. App-owned widget-name publication does not
        require extra Shopify access scopes.
      operationId: updateShopifyCapabilities
      parameters:
        - name: id
          in: path
          required: true
          description: Linked Shopify store ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled_capabilities:
                  type: array
                  description: >-
                    Complete desired set of merchant capabilities. Secure
                    customer support is optional and off by default; enabling it
                    requires current availability. A previously enabled option
                    can be preserved or disabled when it is unavailable.
                  items:
                    type: string
                    enum:
                      - voice_checkout
                      - send_draft_invoice
                      - cancel_orders
                      - update_shipping_address
                      - request_returns
                      - secure_customer_support
                  uniqueItems: true
                  maxItems: 6
                capability_config:
                  $ref: '#/components/schemas/ShopifyCapabilityConfig'
                  description: Merchant policy; omitted preserves existing settings.
                expected_version:
                  type: integer
                  minimum: 0
                  description: >-
                    Version from the latest setup capabilities snapshot; a stale
                    update is rejected.
              required:
                - enabled_capabilities
                - expected_version
      responses:
        '200':
          description: List Shopify assistant tools.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ShopifyCapabilities'
                required:
                  - data
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    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: []
    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
    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.
  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.