Better Data

Developer Resources

API overview

Edit this page

API overview

Interactive reference: Open interactive API reference — try endpoints and inspect schemas in the OpenAPI explorer on the marketing developer surface.

Narrative API hubs explain common workflows; SCM tag reference pages provide OpenAPI-backed endpoint details.

Better Data APIs provide programmatic access for Commerce Chain Optimization and SCM workloads — forecasting, inventory, transfers, alerts, catalog, and related platform operations. All tenant-facing APIs are workspace-scoped (tenant-bound) and require authentication.

Base URL

All API requests should be made to:

1https://app.betterdata.co/api

API groups

Hub pages summarize each area; authoritative path and schema detail is in the OpenAPI bundle. Tag-level references also live under SCM; sessions are documented under Sessions.

chart-lineForecasting API

Scenarios, events, accuracy, and projections — hub + OpenAPI.

packageInventory API

Levels, ATP, adjustments, replenishment, cycle counts — hub + OpenAPI.

arrow-right-leftTransfers API

Recommendations, execution, approvals — hub + OpenAPI.

bellAlerts API

Alert configuration and lifecycle — hub + OpenAPI.

boxCatalog API

Products, categories, attributes — hub + OpenAPI.

Workspaces and tenants

Requests run in the context of a workspace (tenant): API keys, roles, and data isolation are evaluated per workspace. Use organization and workspace identifiers from your admin surface when configuring clients; hub pages describe surface-specific flows.

Authentication

All API requests require authentication. See Authentication for details.

Quick Start:

  1. Obtain an API key from Admin → API
  2. Include the API key in the Authorization header: 
    1Authorization: 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:

1Content-Type: application/json
2Authorization: Bearer YOUR_API_KEY

Request Body

POST and PUT requests should include a JSON body:

1{
2  "field1": "value1",
3  "field2": "value2"
4}

Response Format

Success Response

Successful responses return a JSON body with the requested data:

1{
2  "data": { ... },
3  "pagination": { ... }
4}

Error Response

Error responses include an error message and details:

1{
2  "error": "Error message",
3  "details": { ... }
4}

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; limits also depend on your plan — use response headers or contact support for specifics.

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:

1{
2  "data": [ ... ],
3  "pagination": {
4    "page": 1,
5    "pageSize": 20,
6    "total": 150,
7    "totalPages": 8
8  }
9}

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.

Getting Started

  1. Get an API Key: Create an API key in Admin → API
  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/...).

Webhooks

Event delivery and provider-specific webhook contracts are documented under Webhooks.

Support

For API support:

Permissions & Roles

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