Skip to main content

E-commerce Actions

Integration Overview​

To integrate Filum AI agents with your e-commerce or business systems, you (the customer) need to provide APIs that follow the functionality described in this document. These are the standard APIs required for Filum AI agents to interact with your data for product search, inventory management, order tracking, and store information.

Note:

  • The API endpoints, base URL, and parameter names are flexible and can follow your system's naming conventions. The examples below are for reference only and represent the standard structure.
  • The actual information and data fields provided will depend on your system and what you can expose to Filum.

Authentication​

Filum supports multiple authentication methods for API integration:

  • Basic Authentication
  • Bearer Token Authentication
  • Custom Header Authentication

Include the appropriate authentication credentials in the request header as per your system's requirements. Example for Bearer token:

Authorization: Bearer YOUR_API_KEY

Base URL​

The base URL for your APIs can be any endpoint you provide. The examples below use a standard URL for illustration:

https://{{YOUR_API_BASE_URL}}

1. Search Products​

Endpoint (proposed)​

GET /products/search

Description​

Search for products using keywords, filters, and sorting options.

Query Parameters (proposed)​

ParameterTypeRequiredDescription
keywordstringNoSearch keyword for product name/description
categorystringNoFilter by category ID or name
min_pricenumberNoMinimum price filter
max_pricenumberNoMaximum price filter
in_stockbooleanNoFilter for in-stock products only
sort_bystringNoSort by: price_asc, price_desc, name_asc, name_desc, popularity
pageintegerNoPage number (default: 1)
limitintegerNoItems per page (default: 20, max: 100)

Response​

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "prod_123",
        "name": "iPhone 15 Pro",
        "description": "Latest iPhone with advanced features",
        "price": 999.99,
        "currency": "USD",
        "category": {
          "id": "cat_phones",
          "name": "Smartphones"
        },
        "variants": [
          {
            "sku": "IPH15PRO_128GB_BLACK",
            "name": "128GB Black",
            "price": 999.99,
            "in_stock": true,
            "stock_quantity": 15
          },
          {
            "sku": "IPH15PRO_256GB_BLACK",
            "name": "256GB Black",
            "price": 1099.99,
            "in_stock": true,
            "stock_quantity": 8
          }
        ],
        "images": [
          "https://example.com/iphone15pro_1.jpg",
          "https://example.com/iphone15pro_2.jpg"
        ],
        "rating": 4.8,
        "review_count": 1250
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8
    }
  }
}

Example Request​

curl -X GET "https://{{YOUR_API_BASE_URL}}/products/search?keyword=iphone&category=smartphones&min_price=500&in_stock=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Check Stock​

Endpoint (proposed)​

GET /products/stock/{sku}

Description​

Get real-time stock information for a specific product SKU across all stores.

Path Parameters (proposed)​

ParameterTypeRequiredDescription
skustringYesProduct SKU to check

Response (proposed)​

{
  "success": true,
  "data": {
    "sku": "IPH15PRO_128GB_BLACK",
    "product_name": "iPhone 15 Pro 128GB Black",
    "stores": [
      {
        "store_id": "store_001",
        "store_name": "Downtown Mall",
        "address": "123 Main St, Downtown",
        "stock_quantity": 5,
        "in_stock": true,
        "last_updated": "2024-01-15T10:30:00Z"
      },
      {
        "store_id": "store_002",
        "store_name": "Westside Plaza",
        "address": "456 West Ave, Westside",
        "stock_quantity": 0,
        "in_stock": false,
        "last_updated": "2024-01-15T09:15:00Z"
      }
    ],
    "total_available": 5
  }
}

Example Request​

curl -X GET "https://{{YOUR_API_BASE_URL}}/products/stock/IPH15PRO_128GB_BLACK" \
  -H "Authorization: Bearer YOUR_API_KEY"

3. Get Product Details​

Endpoint (proposed)​

GET /products/{identifier}

Description​

Get detailed information about a specific product using ID, SKU, or URL.

Path Parameters (proposed)​

ParameterTypeRequiredDescription
identifierstringYesProduct ID, SKU, or URL

Query Parameters (proposed)​

ParameterTypeRequiredDescription
include_stockbooleanNoInclude stock information (default: true)
include_reviewsbooleanNoInclude customer reviews (default: false)

Response (proposed)​

{
  "success": true,
  "data": {
    "id": "prod_123",
    "sku": "IPH15PRO_128GB_BLACK",
    "name": "iPhone 15 Pro",
    "description": "The iPhone 15 Pro features the A17 Pro chip, a 48MP main camera, and a titanium design.",
    "specifications": {
      "display": "6.1-inch Super Retina XDR display",
      "processor": "A17 Pro chip",
      "storage": "128GB",
      "camera": "48MP Main + 12MP Ultra Wide + 12MP Telephoto",
      "battery": "Up to 23 hours video playback"
    },
    "price": 999.99,
    "currency": "USD",
    "category": {
      "id": "cat_phones",
      "name": "Smartphones"
    },
    "variants": [
      {
        "sku": "IPH15PRO_128GB_BLACK",
        "name": "128GB Black",
        "price": 999.99,
        "in_stock": true,
        "stock_quantity": 15
      },
      {
        "sku": "IPH15PRO_256GB_BLACK",
        "name": "256GB Black",
        "price": 1099.99,
        "in_stock": true,
        "stock_quantity": 8
      }
    ],
    "offers": [
      {
        "type": "discount",
        "description": "Student discount",
        "discount_percent": 10,
        "valid_until": "2024-12-31"
      }
    ],
    "images": [
      "https://example.com/iphone15pro_1.jpg",
      "https://example.com/iphone15pro_2.jpg"
    ],
    "rating": 4.8,
    "review_count": 1250,
    "availability": {
      "online": true,
      "in_store": true,
      "estimated_delivery": "2-3 business days"
    }
  }
}

Example Request​

curl -X GET "https://{{YOUR_API_BASE_URL}}/products/prod_123?include_stock=true&include_reviews=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

4. Check Order Status​

Endpoint (proposed)​

GET /orders/{order_id}

Description​

Get detailed information about a specific order including status, products, and customer details.

Path Parameters (proposed)​

ParameterTypeRequiredDescription
order_idstringYesOrder ID to retrieve

Response (proposed)​

{
  "success": true,
  "data": {
    "order_id": "ORD_2024_001234",
    "status": "shipped",
    "status_history": [
      {
        "status": "pending",
        "timestamp": "2024-01-10T14:30:00Z",
        "description": "Order placed"
      },
      {
        "status": "confirmed",
        "timestamp": "2024-01-10T15:45:00Z",
        "description": "Payment confirmed"
      },
      {
        "status": "shipped",
        "timestamp": "2024-01-12T09:20:00Z",
        "description": "Package shipped"
      }
    ],
    "customer": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890"
    },
    "shipping_address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "USA"
    },
    "products": [
      {
        "product_id": "prod_123",
        "sku": "IPH15PRO_128GB_BLACK",
        "name": "iPhone 15 Pro 128GB Black",
        "quantity": 1,
        "unit_price": 999.99,
        "total_price": 999.99
      }
    ],
    "order_summary": {
      "subtotal": 999.99,
      "tax": 89.99,
      "shipping": 0.00,
      "total": 1089.98
    },
    "payment_method": "Credit Card",
    "estimated_delivery": "2024-01-15",
    "tracking_number": "1Z999AA1234567890",
    "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA1234567890"
  }
}

Example Request​

curl -X GET "https://{{YOUR_API_BASE_URL}}/orders/ORD_2024_001234" \
  -H "Authorization: Bearer YOUR_API_KEY"

5. Get Stores​

Endpoint (proposed)​

GET /stores

Description​

Get list of stores filtered by location (city/district).

Query Parameters (proposed)​

ParameterTypeRequiredDescription
citystringNoFilter by city name
districtstringNoFilter by district name
radiusnumberNoSearch radius in kilometers (default: 50)
latitudenumberNoLatitude for location-based search
longitudenumberNoLongitude for location-based search

Response (proposed)​

{
  "success": true,
  "data": {
    "stores": [
      {
        "store_id": "store_001",
        "name": "Downtown Mall Store",
        "address": {
          "street": "123 Main Street",
          "city": "New York",
          "state": "NY",
          "zip": "10001",
          "country": "USA"
        },
        "contact": {
          "phone": "+1-555-123-4567",
          "email": "downtown@example.com"
        },
        "opening_hours": {
          "monday": "9:00 AM - 9:00 PM",
          "tuesday": "9:00 AM - 9:00 PM",
          "wednesday": "9:00 AM - 9:00 PM",
          "thursday": "9:00 AM - 9:00 PM",
          "friday": "9:00 AM - 10:00 PM",
          "saturday": "10:00 AM - 10:00 PM",
          "sunday": "11:00 AM - 7:00 PM"
        },
        "location": {
          "latitude": 40.7589,
          "longitude": -73.9851
        },
        "services": ["sales", "repair", "pickup"],
        "is_open": true
      }
    ],
    "total": 1
  }
}

Example Request​

curl -X GET "https://{{YOUR_API_BASE_URL}}/stores?city=New%20York&district=Manhattan" \
  -H "Authorization: Bearer YOUR_API_KEY"

6. Get Product Categories​

Endpoint (proposed)​

GET /categories

Description​

Search and retrieve product categories with optional keyword filtering.

Query Parameters (proposed)​

ParameterTypeRequiredDescription
keywordstringNoSearch keyword for category name
parent_idstringNoFilter by parent category ID
include_childrenbooleanNoInclude subcategories (default: true)

Response (proposed)​

{
  "success": true,
  "data": {
    "categories": [
      {
        "id": "cat_phones",
        "name": "Smartphones",
        "description": "Mobile phones and smartphones",
        "parent_id": null,
        "children": [
          {
            "id": "cat_iphone",
            "name": "iPhone",
            "description": "Apple iPhone models",
            "parent_id": "cat_phones"
          },
          {
            "id": "cat_android",
            "name": "Android Phones",
            "description": "Android smartphones",
            "parent_id": "cat_phones"
          }
        ],
        "product_count": 150
      },
      {
        "id": "cat_laptops",
        "name": "Laptops",
        "description": "Portable computers",
        "parent_id": null,
        "children": [],
        "product_count": 75
      }
    ],
    "total": 2
  }
}

Example Request​

curl -X GET "https://{{YOUR_API_BASE_URL}}/categories?keyword=phone&include_children=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses​

All endpoints return consistent error responses:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid parameter provided",
    "details": {
      "field": "price",
      "issue": "Price must be a positive number"
    }
  }
}

Common Error Codes​

CodeDescription
UNAUTHORIZEDInvalid or missing API key
INVALID_PARAMETERInvalid request parameter
NOT_FOUNDResource not found
RATE_LIMIT_EXCEEDEDToo many requests
INTERNAL_ERRORServer error