Squarespace Commerce Management

naftiko: "1.0.0-alpha1"

info:
  label: "Squarespace Commerce Management"
  description: >-
    Unified commerce management capability combining Squarespace Orders, Products,
    and Inventory APIs. Enables e-commerce operators, integration developers, and
    automation tools to manage the full product lifecycle — catalog management,
    order fulfillment, and stock control — through a single REST API and MCP server.
    Suited for ERP integrations, warehouse management, and multi-channel retail.
  tags:
    - Commerce
    - E-Commerce
    - Inventory
    - Orders
    - Products
    - Squarespace
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SQUARESPACE_API_KEY: SQUARESPACE_API_KEY

capability:
  consumes:
    - import: squarespace-orders
      location: ./shared/orders.yaml
    - import: squarespace-products
      location: ./shared/products.yaml
    - import: squarespace-inventory
      location: ./shared/inventory.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: squarespace-commerce-api
      description: "Unified REST API for Squarespace commerce management."
      resources:
        - path: /v1/orders
          name: orders
          description: "Order history and management"
          operations:
            - method: GET
              name: list-orders
              description: "Retrieve all orders with optional date and status filters"
              call: "squarespace-orders.list-orders"
              with:
                cursor: "rest.cursor"
                modifiedAfter: "rest.modifiedAfter"
                fulfillmentStatus: "rest.fulfillmentStatus"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/orders/{id}
          name: order
          description: "Individual order details"
          operations:
            - method: GET
              name: get-order
              description: "Retrieve a specific order by ID"
              call: "squarespace-orders.get-order"
              with:
                orderId: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/products
          name: products
          description: "Product catalog"
          operations:
            - method: GET
              name: list-products
              description: "Retrieve all products in the catalog"
              call: "squarespace-products.list-products"
              with:
                cursor: "rest.cursor"
                type: "rest.type"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-product
              description: "Create a new product"
              call: "squarespace-products.create-product"
              with:
                type: "rest.type"
                name: "rest.name"
                description: "rest.description"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/products/{id}
          name: product
          description: "Individual product management"
          operations:
            - method: GET
              name: get-product
              description: "Get a specific product"
              call: "squarespace-products.get-product"
              with:
                productId: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-product
              description: "Delete a product from the catalog"
              call: "squarespace-products.delete-product"
              with:
                productId: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/inventory
          name: inventory
          description: "Stock level management"
          operations:
            - method: GET
              name: list-inventory
              description: "Retrieve inventory levels for all variants"
              call: "squarespace-inventory.list-inventory"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/inventory/adjustments
          name: inventory-adjustments
          description: "Bulk inventory adjustment"
          operations:
            - method: POST
              name: adjust-inventory
              description: "Apply stock quantity adjustments"
              call: "squarespace-inventory.adjust-inventory"
              with:
                inventory: "rest.inventory"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: squarespace-commerce-mcp
      transport: http
      description: "MCP server for AI-assisted Squarespace commerce management."
      tools:
        - name: list-orders
          description: >-
            Retrieve all orders from a Squarespace merchant site. Supports filtering
            by fulfillment status and modification date range.
          hints:
            readOnly: true
            idempotent: true
          call: "squarespace-orders.list-orders"
          with:
            cursor: "tools.cursor"
            modifiedAfter: "tools.modifiedAfter"
            fulfillmentStatus: "tools.fulfillmentStatus"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-order
          description: "Retrieve details of a specific order by its ID."
          hints:
            readOnly: true
            idempotent: true
          call: "squarespace-orders.get-order"
          with:
            orderId: "tools.orderId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-products
          description: >-
            Retrieve all products in the Squarespace catalog. Optionally filter
            by product type (PHYSICAL, SERVICE, GIFT_CARD, DIGITAL).
          hints:
            readOnly: true
            idempotent: true
          call: "squarespace-products.list-products"
          with:
            cursor: "tools.cursor"
            type: "tools.type"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-product
          description: "Retrieve a specific product by its ID."
          hints:
            readOnly: true
            idempotent: true
          call: "squarespace-products.get-product"
          with:
            productId: "tools.productId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-product
          description: "Create a new product in the Squarespace catalog."
          hints:
            readOnly: false
            idempotent: false
          call: "squarespace-products.create-product"
          with:
            type: "tools.type"
            name: "tools.name"
            description: "tools.description"
          outputParameters:
            - type: object
              mapping: "$."
        - name: delete-product
          description: "Delete a product from the Squarespace catalog."
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "squarespace-products.delete-product"
          with:
            productId: "tools.productId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-inventory
          description: "Retrieve current stock levels for all product variants."
          hints:
            readOnly: true
            idempotent: true
          call: "squarespace-inventory.list-inventory"
          outputParameters:
            - type: object
              mapping: "$."
        - name: adjust-inventory
          description: "Apply incremental stock quantity adjustments to product variants."
          hints:
            readOnly: false
            idempotent: false
          call: "squarespace-inventory.adjust-inventory"
          with:
            inventory: "tools.inventory"
          outputParameters:
            - type: object
              mapping: "$."