Better Data

API Reference

API Reference

Edit this page

Base URL

1https://gateway.betterdata.io/v1
1http://localhost:3000

Authentication

All API requests require authentication using an API key:

1Authorization: Bearer YOUR_API_KEY

Get your API key from the Better Data Dashboard

SDKs

node-jsTypeScript/Node.js

1npm install @commercegateway/commerce-gateway

pythonPython

1pip install betterdata-gateway

Coming soon!

golangGo

1go get github.com/betterdata/gateway-go

Coming soon!

Quick Example

1import { GatewayClient } from '@commercegateway/commerce-gateway';
2 
3const client = new GatewayClient({
4  apiKey: process.env.BETTERDATA_API_KEY!,
5  baseUrl: 'https://gateway.betterdata.io/v1',
6});
7 
8"cmt">// Search products
9const products = await client.products.search({
10  query: 'wireless headphones',
11  limit: 10,
12});
13 
14"cmt">// Get product details
15const product = await client.products.get('prod_123');
16 
17"cmt">// Add to cart
18const cart = await client.cart.add({
19  productId: 'prod_123',
20  quantity: 2,
21  sessionId: 'session_abc',
22});

Response Format

All API responses follow this structure:

1{
2  "success": true,
3  "data": { ... },
4  "meta": {
5    "requestId": "req_123abc",
6    "timestamp": "2024-12-11T10:00:00Z"
7  }
8}

Success Response

1{
2  "success": true,
3  "data": {
4    "products": [
5      {
6        "id": "prod_123",
7        "name": "Wireless Headphones",
8        "price": 99.99,
9        "inStock": true
10      }
11    ]
12  },
13  "meta": {
14    "requestId": "req_123abc",
15    "timestamp": "2024-12-11T10:00:00Z"
16  }
17}

Error Response

1{
2  "success": false,
3  "error": {
4    "code": "VALIDATION_ERROR",
5    "message": "Invalid query parameter",
6    "details": {
7      "field": "limit",
8      "constraint": "Must be between 1 and 100"
9    }
10  },
11  "meta": {
12    "requestId": "req_123abc",
13    "timestamp": "2024-12-11T10:00:00Z"
14  }
15}

Error Codes

| Code | Status | Description | |------|--------|-------------| | UNAUTHORIZED | 401 | Invalid or missing API key | | FORBIDDEN | 403 | Insufficient permissions | | NOT_FOUND | 404 | Resource not found | | VALIDATION_ERROR | 400 | Invalid request parameters | | RATE_LIMIT_EXCEEDED | 429 | Too many requests | | INTERNAL_ERROR | 500 | Server error | | SERVICE_UNAVAILABLE | 503 | Service temporarily unavailable |

Rate Limiting

API requests are rate-limited per API key:

| Plan | Rate Limit | |------|------------| | Free | 100 requests/minute | | Starter | 1,000 requests/minute | | Growth | 10,000 requests/minute | | Enterprise | Custom |

Rate limit headers are included in every response:

1X-RateLimit-Limit: 1000
2X-RateLimit-Remaining: 999
3X-RateLimit-Reset: 1702281600

Pagination

List endpoints support cursor-based pagination:

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

Response includes pagination metadata:

1{
2  "data": [...],
3  "pagination": {
4    "hasMore": true,
5    "nextCursor": "eyJpZCI6InByb2RfMTQ1In0",
6    "total": 1247
7  }
8}

Filtering

Use query parameters to filter results:

1# Filter by price range
2GET /v1/products?minPrice=50&maxPrice=200
3 
4# Filter by category
5GET /v1/products?category=electronics
6 
7# Filter by availability
8GET /v1/products?inStock=true
9 
10# Combine filters
11GET /v1/products?category=electronics&inStock=true&maxPrice=500

Sorting

Sort results using the sort parameter:

1# Sort by price (ascending)
2GET /v1/products?sort=price
3 
4# Sort by price (descending)
5GET /v1/products?sort=-price
6 
7# Sort by multiple fields
8GET /v1/products?sort=category,-price

Webhooks

Subscribe to real-time events:

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

webhookWebhook Events

View all available webhook events

API Endpoints

gatewayGateway Endpoints

List tools, execute tools, chat completions

clockSession Endpoints

Create, get, update, delete sessions

plugIntegration Endpoints

Connect Shopify, Square, sync products

chart-lineAnalytics Endpoints

Get metrics, attribution, conversion data