AI Shopping Marketplace API

Connect your AI agents to discover products across multiple merchants

🚀 Quick Start

Our API provides two protocols for integration: REST API for simple HTTP requests and Agent-to-Agent (A2A) protocol for advanced conversational commerce.

🌐 REST API

Simple HTTP endpoints perfect for ChatGPT Actions, custom integrations, and traditional applications.

🤖 A2A Protocol

JSON-RPC 2.0 based protocol for sophisticated agent-to-agent communication with conversation history.

REST API Endpoint

POST

Request Example

{
  "buyerAgentId": "buyer_123",
  "buyerAgentName": "Shopping Assistant",
  "query": "comfortable tank tops for summer",
  "filters": {
    "minPrice": 20,
    "maxPrice": 50,
    "tags": ["summer", "casual"]
  },
  "context": {
    "email": "shopper@example.com",
    "location": "New York, USA"
  }
}

Response Example

{
  "products": [
    {
      "id": "gid://shopify/Product/8765432109",
      "title": "Ultra-Soft Summer Tank Top",
      "price": 34.99,
      "merchant": "stylestore.myshopify.com",
      "merchantUrl": "https://stylestore.com",
      "link": "https://stylestore.com/products/ultra-soft-tank",
      "naturalLanguageDescription": "This ultra-soft tank top is perfect for hot summer days. Made from breathable bamboo fabric, it keeps you cool while looking stylish. The relaxed fit and moisture-wicking properties make it ideal for both casual outings and light workouts.",
      "presentationOrder": 1,
      "metadata": {
        "occasions": ["beach vacation", "casual weekend", "yoga class"],
        "styles": ["relaxed fit", "minimalist", "athleisure"],
        "benefits": ["moisture-wicking", "eco-friendly fabric", "temperature regulating"]
      }
    },
    {
      "id": "gid://shopify/Product/8765432110",
      "title": "Classic Cotton Tank",
      "price": 24.99,
      "merchant": "essentials.myshopify.com",
      "merchantUrl": "https://essentials.com",
      "link": "https://essentials.com/products/classic-cotton-tank",
      "naturalLanguageDescription": "A wardrobe essential, this classic cotton tank offers timeless style and comfort. The soft, breathable cotton is perfect for layering or wearing solo on warm days. Available in multiple colors to match any summer outfit.",
      "presentationOrder": 2,
      "metadata": {
        "occasions": ["everyday wear", "layering", "travel"],
        "styles": ["classic", "versatile", "essential"],
        "benefits": ["100% cotton", "machine washable", "fade-resistant"]
      }
    }
  ],
  "metadata": {
    "totalProducts": 2,
    "hasMore": false,
    "aiMessage": "I found 2 comfortable tank tops perfect for summer:\n\n1. Ultra-Soft Summer Tank Top ($34.99) - This ultra-soft tank top is perfect for hot summer days. Made from breathable bamboo fabric, it keeps you cool while looking stylish.\n\n2. Classic Cotton Tank ($24.99) - A wardrobe essential, this classic cotton tank offers timeless style and comfort. The soft, breathable cotton is perfect for layering or wearing solo on warm days.",
    "completeness": "full",
    "focusProducts": ["gid://shopify/Product/8765432109", "gid://shopify/Product/8765432110"]
  }
}

A2A Protocol Endpoint

POST

Message Send Example

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "buyerAgentId": "buyer_123",
    "message": {
      "role": "user",
      "content": "I need comfortable tank tops for my beach vacation"
    }
  },
  "id": 1
}

Response Example

{
  "jsonrpc": "2.0",
  "result": {
    "taskId": "task_1234567890",
    "status": "completed",
    "message": "I found several comfortable tank tops perfect for your beach vacation! Here are the top options:\n\n1. Ultra-Soft Summer Tank Top ($34.99) - Made from breathable bamboo fabric...",
    "products": [
      {
        "id": "gid://shopify/Product/8765432109",
        "title": "Ultra-Soft Summer Tank Top",
        "price": 34.99,
        "merchant": "stylestore.myshopify.com",
        "link": "https://stylestore.com/products/ultra-soft-tank",
        "naturalLanguageDescription": "Perfect for beach vacations...",
        "metadata": {
          "occasions": ["beach vacation", "summer travel"],
          "benefits": ["quick-dry", "sun protection"]
        }
      }
    ]
  },
  "id": 1
}

🔒 Security & Authentication

Current Implementation (Development)

Both endpoints support authentication via:

  • Authorization: Bearer YOUR_API_KEY header
  • X-API-Key: YOUR_API_KEY header
🔐 Token-based Authentication

Production Security (Planned)

OAuth 2.0 Integration

Secure authentication flow with refresh tokens and scoped permissions

Request Signing

HMAC-SHA256 request signatures for webhook notifications

🏗️ Architecture & Approach

Building a Global Product Discovery Network

Our API endpoints are built on modern, scalable architecture designed to handle millions of product searches across thousands of merchants.

AI-Enhanced Search

Our unique approach to natural language understanding combines contextual modeling with dynamic product matching, ensuring queries are interpreted based on intent rather than just keywords.

Multi-Store Federation

Aggregate products from multiple Shopify stores while maintaining merchant autonomy and unique positioning.

Conversation Memory

A2A protocol maintains conversation context, enabling follow-up questions like "tell me more about the second one".

Real-time Scoring

Dynamic relevance scoring based on query matching, product attributes, and merchant-specific positioning.

Building something cool?

Let’s connect.