API Overview - GXO.dev Developer Documentation

The GXO.dev API provides comprehensive access to agentic commerce functionality, enabling developers to integrate AI agent commerce capabilities into their applications. This guide covers authentication, rate limiting, request/response formats, and error handling.

API 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. From Your Dashboard

   • Go to Settings > API Keys
   • Click "Generate New API Key"
   • Copy and securely store your API key
   • API keys are never shown again after generation

2. API Key Permissions

   • Read-only: View data and analytics
   • Read/Write: Full access to all API endpoints
   • Admin: Administrative functions and user management

API Key Security

Best Practices:

• Store API keys securely (environment variables, secret managers)
• Never expose API keys in client-side code
• Rotate API keys regularly
• Use different keys for different environments

Security Features:

• API keys are tied to your account
• Rate limiting per API key
• Audit logging for all API usage
• Revocation capabilities

API Versioning

Current Version

API Version: v1 Base URL: https://api.gxo.dev/v1

Version Headers

Include the API version in your requests:

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

Version Deprecation

• 6 months notice for breaking changes
• 3 months notice for feature deprecation
• Migration guides provided for all changes
• Backward compatibility maintained when possible

Rate Limiting

Rate Limit Headers

All API responses include rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Rate Limit Tiers

Starter Plan:

• 10,000 requests per month
• 100 requests per minute
• Burst limit: 200 requests per minute

Pro Plan:

• 100,000 requests per month
• 1,000 requests per minute
• Burst limit: 2,000 requests per minute

Enterprise Plan:

• 1,000,000 requests per month
• 10,000 requests per minute
• Burst limit: 20,000 requests per minute

Scale Plan:

• Unlimited requests
• 100,000 requests per minute
• Burst limit: 200,000 requests per minute

Rate Limit Handling

Exponential Backoff:

async function makeAPICall() {
  const maxRetries = 3;
  let retryCount = 0;
  
  while (retryCount < maxRetries) {
    try {
      const response = await fetch('/api/endpoint');
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        await new Promise(resolve => 
          setTimeout(resolve, retryAfter * 1000)
        );
        retryCount++;
        continue;
      }
      
      return response;
    } catch (error) {
      retryCount++;
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, retryCount) * 1000)
      );
    }
  }
}

Request/Response Formats

Request Format

Content-Type: application/json Accept: application/json

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{"name": "Product Name", "price": 29.99}' \
     https://api.gxo.dev/v1/products

Response Format

Success Response:

{
  "success": true,
  "data": {
    "id": "prod_123",
    "name": "Product Name",
    "price": 29.99,
    "created_at": "2024-01-15T10:00:00Z"
  },
  "meta": {
    "request_id": "req_123",
    "timestamp": "2024-01-15T10:00:00Z"
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "field": "price",
      "reason": "Must be a positive number"
    }
  },
  "meta": {
    "request_id": "req_123",
    "timestamp": "2024-01-15T10:00:00Z"
  }
}

Error Handling

HTTP Status Codes

Success Codes:

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 204 No Content: Request successful, no content returned

Client Error Codes:

• 400 Bad Request: Invalid request data
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 409 Conflict: Resource already exists
• 422 Unprocessable Entity: Validation error
• 429 Too Many Requests: Rate limit exceeded

Server Error Codes:

• 500 Internal Server Error: Server error
• 502 Bad Gateway: Upstream service error
• 503 Service Unavailable: Service temporarily unavailable
• 504 Gateway Timeout: Request timeout

Error Codes

Authentication Errors:

• INVALID_API_KEY: API key is invalid or expired
• MISSING_API_KEY: API key not provided
• INSUFFICIENT_PERMISSIONS: API key lacks required permissions

Validation Errors:

• VALIDATION_ERROR: Request data validation failed
• MISSING_REQUIRED_FIELD: Required field is missing
• INVALID_FIELD_VALUE: Field value is invalid
• FIELD_TOO_LONG: Field value exceeds maximum length

Rate Limiting Errors:

• RATE_LIMIT_EXCEEDED: API rate limit exceeded
• QUOTA_EXCEEDED: Monthly quota exceeded
• BURST_LIMIT_EXCEEDED: Burst rate limit exceeded

Resource Errors:

• RESOURCE_NOT_FOUND: Requested resource not found
• RESOURCE_ALREADY_EXISTS: Resource already exists
• RESOURCE_CONFLICT: Resource conflict

Error Handling Best Practices

Retry Logic:

async function handleAPIError(error) {
  if (error.status === 429) {
    // Rate limit exceeded - retry with backoff
    const retryAfter = error.headers.get('Retry-After');
    await new Promise(resolve => 
      setTimeout(resolve, retryAfter * 1000)
    );
    return retry();
  }
  
  if (error.status >= 500) {
    // Server error - retry with exponential backoff
    await new Promise(resolve => 
      setTimeout(resolve, Math.pow(2, retryCount) * 1000)
    );
    return retry();
  }
  
  // Client error - don't retry
  throw error;
}

Error Logging:

function logAPIError(error) {
  console.error('API Error:', {
    status: error.status,
    code: error.code,
    message: error.message,
    requestId: error.requestId,
    timestamp: new Date().toISOString()
  });
}

API Endpoints Overview

Product Management

Product Endpoints:

• GET /products - List all products
• GET /products/{id} - Get product details
• POST /products - Create new product
• PUT /products/{id} - Update product
• DELETE /products/{id} - Delete product

Product Feed Endpoints:

• GET /feeds - List product feeds
• GET /feeds/{id} - Get feed details
• POST /feeds - Create new feed
• PUT /feeds/{id} - Update feed
• DELETE /feeds/{id} - Delete feed

Platform Integration

Integration Endpoints:

• GET /integrations - List platform integrations
• GET /integrations/{id} - Get integration details
• POST /integrations - Create new integration
• PUT /integrations/{id} - Update integration
• DELETE /integrations/{id} - Delete integration

Sync Endpoints:

• POST /integrations/{id}/sync - Trigger manual sync
• GET /integrations/{id}/sync/status - Get sync status
• GET /integrations/{id}/sync/history - Get sync history

Analytics

Analytics Endpoints:

• GET /analytics/overview - Get analytics overview
• GET /analytics/products - Get product analytics
• GET /analytics/ai-interactions - Get AI interaction analytics
• GET /analytics/conversions - Get conversion analytics

Report Endpoints:

• GET /reports - List available reports
• GET /reports/{id} - Get report details
• POST /reports - Generate new report
• GET /reports/{id}/download - Download report

SDKs and Libraries

Official SDKs

JavaScript/TypeScript SDK:

npm install @gxo/sdk

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

const client = new GXOClient({
  apiKey: 'your-api-key',
  environment: 'production'
});

// List products
const products = await client.products.list();

// Create product
const product = await client.products.create({
  name: 'New Product',
  price: 29.99
});

Python SDK:

pip install gxo-sdk

from gxo import GXOClient

client = GXOClient(
    api_key='your-api-key',
    environment='production'
)

# List products
products = client.products.list()

# Create product
product = client.products.create({
    'name': 'New Product',
    'price': 29.99
})

Community SDKs

PHP SDK:

composer require gxo/php-sdk

Ruby SDK:

gem install gxo-sdk

Go SDK:

go get github.com/gxo/go-sdk

Webhooks

Webhook Events

Product Events:

• product.created - New product created
• product.updated - Product updated
• product.deleted - Product deleted

Feed Events:

• feed.generated - New feed generated
• feed.updated - Feed updated
• feed.published - Feed published

Integration Events:

• integration.connected - Platform connected
• integration.disconnected - Platform disconnected
• integration.sync.completed - Sync completed
• integration.sync.failed - Sync failed

Webhook Configuration

Setting Up Webhooks:

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://your-app.com/webhooks/gxo",
       "events": ["product.created", "product.updated"],
       "secret": "your-webhook-secret"
     }' \
     https://api.gxo.dev/v1/webhooks

Webhook Security:

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Testing

Sandbox Environment

Sandbox URL: https://api-sandbox.gxo.dev/v1 Test API Key: Use sandbox API keys for testing

Test Data

Test Products:

• Pre-configured test products
• Mock AI agent interactions
• Sample analytics data
• Test webhook events

Integration Testing

Automated Testing:

describe('GXO API Integration', () => {
  it('should create and retrieve products', async () => {
    const product = await client.products.create({
      name: 'Test Product',
      price: 29.99
    });
    
    expect(product.id).toBeDefined();
    expect(product.name).toBe('Test Product');
  });
});

Next Steps

Now that you understand the API basics:

• ACP API Reference
• Webhook Integration
• SDK Documentation
• Integration Examples

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

Developer Resources

• API Reference: Complete API Documentation
• SDK Documentation: SDK Guides
• Code Examples: Integration Examples
• Community: Developer Discord

Build powerful agentic commerce applications with the GXO.dev API. Integrate AI agent commerce capabilities into your applications today.