Woocommerce template

The WooCommerce Custom Action connects your Agent to your WooCommerce store so it can retrieve product information and use it when answering customer questions. This setup includes:

A predefined OpenAPI schema for WooCommerce
API key authentication
Query parameters for your WooCommerce credentials
A health check configuration

After setting up the Action, you can validate it, activate it, and test it in the Playground.

Set up the action

Go to Agents in Watermelon and select the agent you want to add the action to.
Select Actions in the left menu.
In the Actions catalog, click Custom action.
Click Create new Action.
Fill in the fields below.

General details

Action name
WooCommerce product and order status Description
This action lets you get product information and use it in your chatbot when customers ask for it. BaseURL
[YOUR WOOCOMMERCE API URL] Use your WooCommerce REST API URL, for example: https://yourdomain.com/wp-json/wc/v3/

Authentication

For Authorization Header, select API key. For Auth Type, select Custom. For Add to, select Query parameters. Add the following query parameters: Query name #1
consumer_key Query value #1
[YOUR CONSUMER KEY] Query name #2
consumer_secret Query value #2
[YOUR CONSUMER SECRET] Replace these values with the Consumer Key and Consumer Secret from your WooCommerce REST API credentials.

This article explains how to generate your API keys in WooCommerce.

Health check

Health check URL
https://www.yourdomain.com/health_check Replace this URL with the health check endpoint you want Watermelon to use. Instruction

You should respond with the following message or a similar variation: Sorry, something went wrong on our end. Can I assist you with anything else? Please let me know how I can help.

This can be left empty, if you do not have an URL to perform a health check.

Schema

Paste the WooCommerce schema into the Schema field:

openapi: 3.0.0
info:
  title: Fietszijspan WooCommerce API
  description: API for retrieving products and order status from Fietszijspan. Use this to answer short, practical customer questions about products, availability, prices, and order status.
  version: "1.0"

servers:
  - url: https://fietszijspan.com/wp-json/wc/v3

security:
  - consumerKey: []
    consumerSecret: []

paths:
  /products:
    get:
      summary: Search and retrieve products
      description: Use this endpoint to find products the customer is asking for. Search by product name, SKU, category, price range, or stock status.
      parameters:
        - name: search
          in: query
          required: false
          description: Search for products by name or keyword.
          schema:
            type: string

        - name: sku
          in: query
          required: false
          description: Search for a product by SKU.
          schema:
            type: string

        - name: slug
          in: query
          required: false
          description: Search for a product by slug.
          schema:
            type: string

        - name: category
          in: query
          required: false
          description: Limit products to a specific WooCommerce category ID.
          schema:
            type: string

        - name: stock_status
          in: query
          required: false
          description: Filter products by stock status.
          schema:
            type: string
            enum:
              - instock
              - outofstock
              - onbackorder

        - name: min_price
          in: query
          required: false
          description: Minimum product price.
          schema:
            type: string

        - name: max_price
          in: query
          required: false
          description: Maximum product price.
          schema:
            type: string

        - name: on_sale
          in: query
          required: false
          description: Show only products that are currently on sale.
          schema:
            type: boolean

        - name: featured
          in: query
          required: false
          description: Show only featured products.
          schema:
            type: boolean

        - name: orderby
          in: query
          required: false
          description: Sort products by a specific field.
          schema:
            type: string
            enum:
              - date
              - id
              - title
              - slug
              - price
              - popularity
              - rating

        - name: order
          in: query
          required: false
          description: Sort direction.
          schema:
            type: string
            enum:
              - asc
              - desc

        - name: page
          in: query
          required: false
          description: Page number.
          schema:
            type: integer

        - name: per_page
          in: query
          required: false
          description: Number of products to return. Use a small number unless the customer asks for many options.
          schema:
            type: integer
            default: 10

      responses:
        "200":
          description: Products found.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Product"
        "400":
          description: Bad request.
        "401":
          description: Authentication failed.
        "404":
          description: No products found.

  /products/{id}:
    get:
      summary: Retrieve a specific product
      description: Use this endpoint when the product ID is known and the customer asks about a specific product.
      parameters:
        - name: id
          in: path
          required: true
          description: WooCommerce product ID.
          schema:
            type: integer

      responses:
        "200":
          description: Product details found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "401":
          description: Authentication failed.
        "404":
          description: Product not found.

  /orders/{id}:
    get:
      summary: Retrieve order status
      description: Use this endpoint to check the status of a customer's order when the WooCommerce order ID is known. Only share basic order status and avoid exposing sensitive customer or payment details.
      parameters:
        - name: id
          in: path
          required: true
          description: WooCommerce order ID.
          schema:
            type: integer

      responses:
        "200":
          description: Order found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "401":
          description: Authentication failed.
        "404":
          description: Order not found.

components:
  securitySchemes:
    consumerKey:
      type: apiKey
      in: query
      name: consumer_key

    consumerSecret:
      type: apiKey
      in: query
      name: consumer_secret

  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
          description: Unique product ID.

        name:
          type: string
          description: Product name.

        slug:
          type: string
          description: Product slug.

        permalink:
          type: string
          format: uri
          description: Product page URL.

        type:
          type: string
          description: Product type.
          enum:
            - simple
            - grouped
            - external
            - variable

        status:
          type: string
          description: Product publication status.

        description:
          type: string
          description: Full product description.

        short_description:
          type: string
          description: Short product description.

        sku:
          type: string
          description: Product SKU.

        price:
          type: string
          description: Current product price.

        regular_price:
          type: string
          description: Regular product price.

        sale_price:
          type: string
          description: Sale price, if available.

        on_sale:
          type: boolean
          description: Whether the product is currently on sale.

        purchasable:
          type: boolean
          description: Whether the product can be purchased.

        stock_status:
          type: string
          description: Current stock status.
          enum:
            - instock
            - outofstock
            - onbackorder

        stock_quantity:
          type: integer
          nullable: true
          description: Available stock quantity, if stock is managed.

        backorders_allowed:
          type: boolean
          description: Whether backorders are allowed.

        weight:
          type: string
          description: Product weight.

        dimensions:
          type: object
          properties:
            length:
              type: string
            width:
              type: string
            height:
              type: string

        categories:
          type: array
          description: Product categories.
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              slug:
                type: string

        images:
          type: array
          description: Product images.
          items:
            type: object
            properties:
              id:
                type: integer
              src:
                type: string
                format: uri
              name:
                type: string
              alt:
                type: string

        attributes:
          type: array
          description: Product attributes, such as size, colour, model, or compatibility.
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              visible:
                type: boolean
              variation:
                type: boolean
              options:
                type: array
                items:
                  type: string

        variations:
          type: array
          description: Variation IDs for variable products.
          items:
            type: integer

    Order:
      type: object
      properties:
        id:
          type: integer
          description: WooCommerce order ID.

        number:
          type: string
          description: Order number shown to the customer.

        status:
          type: string
          description: Current order status.
          enum:
            - pending
            - processing
            - on-hold
            - completed
            - cancelled
            - refunded
            - failed
            - checkout-draft

        date_created:
          type: string
          description: Date the order was created.

        date_modified:
          type: string
          description: Date the order was last updated.

        total:
          type: string
          description: Total order amount.

        currency:
          type: string
          description: Order currency.

        payment_method_title:
          type: string
          description: Payment method title.

        shipping_total:
          type: string
          description: Shipping cost.

        shipping_lines:
          type: array
          description: Shipping method details.
          items:
            type: object
            properties:
              method_title:
                type: string
              total:
                type: string

        line_items:
          type: array
          description: Products included in the order.
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              product_id:
                type: integer
              variation_id:
                type: integer
              quantity:
                type: integer
              total:
                type: string

        customer_note:
          type: string
          description: Customer note, if available.

Click Validate to check the schema.

Example in Watermelon

When everything is configured correctly, click Save and then Activate. Finally, test the Action in the Playground to make sure your Agent can retrieve the expected WooCommerce product information.

Editing an Action Template

After setting up an Action, you can adjust it to your use case. For example, you can add endpoints to the schema, change parameters, or update the name and description. Be careful when changing authentication settings or existing endpoints, as this can prevent the Action from connecting to the API.

Troubleshooting

Issue	Likely cause	What to check
Validation failed	Invalid OpenAPI schema	Check the schema for missing or unsupported fields.
401 Unauthorized	Incorrect WooCommerce credentials	Check your Consumer Key and Consumer Secret.
404 Not Found	Incorrect store URL or endpoint	Check the BaseURL and endpoint path.
Action does not return the expected data	Schema or parameter mismatch	Check the endpoint parameters and API response structure.
Health check fails	Health check endpoint cannot be reached	Check the Health check URL and authentication.

Get started

Build your agent

Publish your agent

Inbox

Contact management

Analytics

Integrations

Guides

Plans & pricing

Resources

Developer resources

Trust & privacy

Set up the action

General details

Authentication

Health check

Schema

Example in Watermelon

Editing an Action Template

Troubleshooting

​Set up the action

​General details

​Authentication

​Health check

​Schema

​Example in Watermelon

​Editing an Action Template

​Troubleshooting

Set up the action

General details

Authentication

Health check

Schema

Example in Watermelon

Editing an Action Template

Troubleshooting