API Reference - Complete GXO.dev API Documentation

The GXO.dev API provides comprehensive access to agentic commerce functionality. This complete API reference covers all endpoints, authentication, request/response formats, and error handling for developers.

API Overview

Base URL

Production API

https://api.gxo.dev/v1

Staging API

https://api-staging.gxo.dev/v1

Authentication

API Key Authentication All API requests require authentication using your API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.gxo.dev/v1/products

Getting Your API Key

1. Navigate to Settings > API Keys in your dashboard
2. Click "Generate New API Key"
3. Copy and securely store your API key
4. API keys are never shown again after generation

Rate Limiting

Rate Limits

• Starter Plan: 10,000 requests/month
• Pro Plan: 100,000 requests/month
• Enterprise Plan: 1,000,000 requests/month
• Scale Plan: Unlimited requests

Rate Limit Headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9999
X-RateLimit-Reset: 1640995200

Products API

Get Products

Endpoint: GET /products

Parameters:

• limit (optional): Number of products to return (default: 50, max: 250)
• offset (optional): Number of products to skip (default: 0)
• category (optional): Filter by product category
• status (optional): Filter by product status (active, inactive, draft)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.gxo.dev/v1/products?limit=10&category=electronics"

Example Response:

{
  "products": [
    {
      "id": "prod_123",
      "name": "Premium Wireless Headphones",
      "description": "High-quality wireless headphones with noise cancellation",
      "price": 199.99,
      "currency": "USD",
      "status": "active",
      "category": "Electronics > Audio",
      "images": [
        "https://example.com/image1.jpg"
      ],
      "attributes": {
        "brand": "TechBrand",
        "features": ["Wireless", "Noise Cancellation", "Bluetooth 5.0"]
      },
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 100,
    "has_more": true
  }
}

Get Product by ID

Endpoint: GET /products/{id}

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.gxo.dev/v1/products/prod_123"

Example Response:

{
  "id": "prod_123",
  "name": "Premium Wireless Headphones",
  "description": "High-quality wireless headphones with noise cancellation",
  "price": 199.99,
  "currency": "USD",
  "status": "active",
  "category": "Electronics > Audio",
  "images": [
    "https://example.com/image1.jpg"
  ],
  "attributes": {
    "brand": "TechBrand",
    "features": ["Wireless", "Noise Cancellation", "Bluetooth 5.0"]
  },
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Feeds API

Get Product Feeds

Endpoint: GET /feeds

Parameters:

• format (optional): Feed format (json, csv, xml)
• status (optional): Feed status (active, inactive, processing)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.gxo.dev/v1/feeds?format=json"

Example Response:

{
  "feeds": [
    {
      "id": "feed_123",
      "name": "Main Product Feed",
      "format": "json",
      "status": "active",
      "url": "https://api.gxo.dev/v1/feeds/feed_123/export",
      "last_updated": "2024-01-15T10:00:00Z",
      "product_count": 150
    }
  ]
}

Generate Feed

Endpoint: POST /feeds

Request Body:

{
  "name": "New Product Feed",
  "format": "json",
  "products": ["prod_123", "prod_456"],
  "filters": {
    "category": "electronics",
    "status": "active"
  }
}

Example Response:

{
  "id": "feed_456",
  "name": "New Product Feed",
  "format": "json",
  "status": "processing",
  "url": "https://api.gxo.dev/v1/feeds/feed_456/export",
  "estimated_completion": "2024-01-15T10:05:00Z"
}

Analytics API

Get Analytics

Endpoint: GET /analytics

Parameters:

• start_date (optional): Start date for analytics (ISO 8601)
• end_date (optional): End date for analytics (ISO 8601)
• metric (optional): Specific metric to retrieve

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.gxo.dev/v1/analytics?start_date=2024-01-01&end_date=2024-01-31"

Example Response:

{
  "analytics": {
    "period": {
      "start_date": "2024-01-01T00:00:00Z",
      "end_date": "2024-01-31T23:59:59Z"
    },
    "metrics": {
      "total_products": 150,
      "ai_interactions": 1250,
      "discovery_rate": 0.85,
      "conversion_rate": 0.12,
      "revenue": 15420.50
    },
    "trends": {
      "ai_interactions": {
        "daily_average": 40.3,
        "growth_rate": 0.15
      },
      "conversion_rate": {
        "daily_average": 0.12,
        "growth_rate": 0.08
      }
    }
  }
}

Integrations API

Get Integrations

Endpoint: GET /integrations

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.gxo.dev/v1/integrations"

Example Response:

{
  "integrations": [
    {
      "id": "int_123",
      "platform": "shopify",
      "status": "connected",
      "shop_domain": "mystore.myshopify.com",
      "last_sync": "2024-01-15T10:00:00Z",
      "product_count": 150
    }
  ]
}

Test Integration

Endpoint: POST /integrations/{id}/test

Example Request:

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.gxo.dev/v1/integrations/int_123/test"

Example Response:

{
  "status": "success",
  "message": "Integration test completed successfully",
  "details": {
    "connection_status": "connected",
    "sync_status": "success",
    "product_count": 150,
    "last_sync": "2024-01-15T10:00:00Z"
  }
}

Error Handling

Error Response Format

All API errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": "Missing required parameter: product_id"
  }
}

Common Error Codes

Authentication Errors

• unauthorized: Invalid or missing API key
• forbidden: Insufficient permissions
• rate_limit_exceeded: Rate limit exceeded

Request Errors

• invalid_request: Invalid request format
• missing_parameter: Required parameter missing
• invalid_parameter: Invalid parameter value

Server Errors

• internal_error: Internal server error
• service_unavailable: Service temporarily unavailable
• timeout: Request timeout

Error Handling Example

fetch('https://api.gxo.dev/v1/products', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => {
  if (!response.ok) {
    return response.json().then(error => {
      throw new Error(error.error.message);
    });
  }
  return response.json();
})
.catch(error => {
  console.error('API Error:', error.message);
});

SDKs and Libraries

JavaScript SDK

Installation:

npm install @gxo/sdk

Usage:

import { GXOClient } from '@gxo/sdk';

const client = new GXOClient({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.gxo.dev/v1'
});

// Get products
const products = await client.products.list({
  limit: 10,
  category: 'electronics'
});

// Get analytics
const analytics = await client.analytics.get({
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Python SDK

Installation:

pip install gxo-sdk

Usage:

from gxo import GXOClient

client = GXOClient(
    api_key='YOUR_API_KEY',
    base_url='https://api.gxo.dev/v1'
)

# Get products
products = client.products.list(
    limit=10,
    category='electronics'
)

# Get analytics
analytics = client.analytics.get(
    start_date='2024-01-01',
    end_date='2024-01-31'
)

Webhooks

Webhook Events

Available Events:

• product.created: New product created
• product.updated: Product updated
• product.deleted: Product deleted
• feed.generated: New feed generated
• integration.connected: Integration connected
• integration.disconnected: Integration disconnected

Webhook Configuration

Set Webhook URL:

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://your-app.com/webhooks/gxo"}' \
     "https://api.gxo.dev/v1/webhooks"

Webhook Payload Example:

{
  "event": "product.created",
  "data": {
    "id": "prod_123",
    "name": "Premium Wireless Headphones",
    "price": 199.99,
    "status": "active"
  },
  "timestamp": "2024-01-15T10:00:00Z"
}

Next Steps

Now that you understand the API:

• Set Up Authentication
• Test API Integration
• Monitor API Usage
• Join Developer Community

Support and Resources

Getting Help

• Documentation: Comprehensive guides for all features
• Support: Email support for all plans
• Community: Discord community for peer support
• Training: Video tutorials and webinars

API Resources

• API Documentation: Complete API Reference
• SDK Documentation: SDK Guides
• Webhook Guide: Webhook Integration
• Community: Developer Discord Community

The GXO.dev API provides comprehensive access to agentic commerce functionality. Build powerful integrations and applications with our developer-friendly API.