API Reference

Authorization: Bearer YOUR_API_KEY

import { GatewayClient } from '@betterdata/commerce-gateway';

const client = new GatewayClient({
  apiKey: process.env.BETTERDATA_API_KEY!,
  baseUrl: 'https://gateway.betterdata.io/v1',
});

// Search products
const products = await client.products.search({
  query: 'wireless headphones',
  limit: 10,
});

// Get product details
const product = await client.products.get('prod_123');

// Add to cart
const cart = await client.cart.add({
  productId: 'prod_123',
  quantity: 2,
  sessionId: 'session_abc',
});

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_123abc",
    "timestamp": "2024-12-11T10:00:00Z"
  }
}

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "prod_123",
        "name": "Wireless Headphones",
        "price": 99.99,
        "inStock": true
      }
    ]
  },
  "meta": {
    "requestId": "req_123abc",
    "timestamp": "2024-12-11T10:00:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameter",
    "details": {
      "field": "limit",
      "constraint": "Must be between 1 and 100"
    }
  },
  "meta": {
    "requestId": "req_123abc",
    "timestamp": "2024-12-11T10:00:00Z"
  }
}

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

GET /v1/products?limit=20&cursor=eyJpZCI6InByb2RfMTIzIn0

{
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6InByb2RfMTQ1In0",
    "total": 1247
  }
}

# Filter by price range
GET /v1/products?minPrice=50&maxPrice=200

# Filter by category
GET /v1/products?category=electronics

# Filter by availability
GET /v1/products?inStock=true

# Combine filters
GET /v1/products?category=electronics&inStock=true&maxPrice=500

# Sort by price (ascending)
GET /v1/products?sort=price

# Sort by price (descending)
GET /v1/products?sort=-price

# Sort by multiple fields
GET /v1/products?sort=category,-price

POST /v1/webhooks
{
  "url": "https://your-app.com/webhooks",
  "events": ["product.created", "order.completed"]
}