Skip to main content

​
API Overview

The Better Data SCM API provides programmatic access to forecasting, inventory, transfers, alerts, and catalog management. All APIs are tenant-scoped and require authentication.
Scope: This documentation covers tenant-facing APIs only. SuperAdmin endpoints (tenant provisioning, entitlements, billing overrides) are excluded. Internal cron endpoints are also excluded unless they’re tenant-configurable.

​
Base URL

All API requests should be made to: 
https://app.betterdata.co/api

​
API Groups

The API is organized into logical groups:

Forecasting API

Forecast scenarios, events, accuracy metrics, and channel projections

Inventory API

Inventory levels, analytics, channel-location ATP, and cycle counts

Transfers API

Transfer recommendations, approval, and execution

Alerts API

Alert configuration, history, and triggering

Catalog API

Products, categories, attributes, and taxonomies

​
Authentication

All API requests require authentication. See Authentication for details. Quick Start:
  1. Obtain an API key from Admin → Integrations → API Keys
  2. Include the API key in the Authorization header: 
    Authorization: Bearer YOUR_API_KEY
  3. Ensure your API key has the required permissions for the endpoints you’re using

​
Request Format

​
Headers

All requests must include: 
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

​
Request Body

POST and PUT requests should include a JSON body: 
{
  "field1": "value1",
  "field2": "value2"
}

​
Response Format

​
Success Response

Successful responses return a JSON body with the requested data: 
{
  "data": { ... },
  "pagination": { ... }
}

​
Error Response

Error responses include an error message and details: 
{
  "error": "Error message",
  "details": { ... }
}

​
HTTP Status Codes

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required or invalid
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict (e.g., duplicate)
  • 500 Internal Server Error: Server error

​
Rate Limits

API requests are rate-limited to prevent abuse. See Rate Limits for details. Default Limits:
  • 100 requests per minute per API key
  • 1000 requests per hour per API key
Rate limit headers are included in all responses:
  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time when rate limit resets

​
Pagination

List endpoints support pagination: Query Parameters:
  • page: Page number (default: 1)
  • limit: Items per page (default: 20, max: 100)
Response: 
{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 150,
    "totalPages": 8
  }
}

​
Filtering and Sorting

Many list endpoints support filtering and sorting: Filtering:
  • Use query parameters to filter results
  • Example: ?status=ACTIVE&locationId=loc_123
Sorting:
  • Use sortBy and sortOrder query parameters
  • Example: ?sortBy=createdAt&sortOrder=desc

​
Common Errors

See Common Errors for detailed error handling guidance. Common Error Codes:
  • UNAUTHORIZED: Authentication required
  • FORBIDDEN: Insufficient permissions
  • VALIDATION_ERROR: Invalid request parameters
  • NOT_FOUND: Resource not found
  • CONFLICT: Resource conflict

​
Beta Endpoints

Some endpoints are marked as Beta and may change without notice. Beta endpoints are indicated with a warning callout in their documentation.
Beta: This endpoint is in beta and may change. Use with caution.

​
Getting Started

  1. Get an API Key: Create an API key in Admin → Integrations → API Keys
  2. Read Authentication Guide: See Authentication
  3. Explore API Groups: Browse the API groups above
  4. Try Example Requests: Each API group includes example requests

​
API Versioning

The API is currently at version 1.0. Future versions will be indicated in the URL path (e.g., /api/v2/...).

​
Support

For API support:
  • Email: support@betterdata.co
  • Documentation: This documentation site
  • Issues: Report issues through your organization’s support channel

​
Permissions & Roles

API access requires an API key with appropriate permissions. Contact your organization administrator to create an API key.