Transfers API

API reference for transfer recommendations, approval, and execution

Transfers API

The Transfers API provides endpoints for managing internal stock transfer recommendations, approval workflows, and execution.

Scope: Tenant-scoped; requires authenticated org context
Availability: Not available in SuperAdmin

Authentication

All requests require authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Base URL

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

Headers

All requests must include:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Endpoints

Method	Path	Summary	Auth	Stability	Permissions
GET	/api/inventory/transfers	List inventory transfers	session	stable	transfers.read
POST	/api/inventory/transfers	Create inventory transfer	session	stable	transfers.write
GET	/api/inventory/transfers/[id]	Get inventory transfer	session	stable	transfers.read
POST	/api/inventory/transfers/[id]	Update inventory transfer	session	stable	transfers.write
GET	/api/inventory/transfers/bins	Get transfer bins	session	stable	transfers.read
GET	/api/transfers/recommendations	List transfer recommendations	session	stable	transfers.read
POST	/api/transfers/recommendations	Generate new transfer recommendations	session	stable	transfers.write
GET	/api/transfers/recommendations/[id]	Get a specific recommendation	session	stable	transfers.read
POST	/api/transfers/recommendations/[id]/approve	Approve a transfer recommendation	session	stable	transfers.approve
POST	/api/transfers/recommendations/[id]/execute	Execute a transfer recommendation	session	stable	transfers.execute
POST	/api/transfers/recommendations/[id]/reject	Reject a transfer recommendation	session	stable	transfers.approve
GET	/api/transfers/recommendations/pending	Get pending recommendations	session	stable	transfers.read

Example Requests

List Transfer Recommendations

curl -X GET "https://app.betterdata.co/api/transfers/recommendations?status=PENDING&priority=URGENT&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "recommendations": [
    {
      "id": "rec_123",
      "productMasterId": "prod_123",
      "sourceLocationId": "loc_456",
      "destLocationId": "loc_789",
      "quantity": 50,
      "priority": "URGENT",
      "status": "PENDING",
      "reason": "Stock imbalance detected",
      "estimatedROI": 0.15,
      "createdAt": "2024-03-01T00:00:00Z"
    }
  ],
  "total": 25,
  "limit": 50,
  "offset": 0
}

Generate Transfer Recommendations

curl -X POST "https://app.betterdata.co/api/transfers/recommendations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "loc_123",
    "minStockDifferencePct": 0.2,
    "requirePositiveROI": true,
    "unitMargin": 10.00
  }'

Response:

{
  "success": true,
  "created": 15,
  "recommendations": [
    {
      "id": "rec_456",
      "productMasterId": "prod_789",
      "sourceLocationId": "loc_123",
      "destLocationId": "loc_456",
      "quantity": 25,
      "priority": "HIGH",
      "status": "PENDING",
      "reason": "High stock at source, low stock at destination",
      "estimatedROI": 0.12
    }
  ]
}

Approve Transfer Recommendation

curl -X POST "https://app.betterdata.co/api/transfers/recommendations/rec_123/approve" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Approved for immediate transfer"
  }'

Response:

{
  "success": true,
  "recommendation": {
    "id": "rec_123",
    "status": "APPROVED",
    "approvedAt": "2024-03-01T12:00:00Z",
    "approvedBy": "user_123"
  }
}

Common Errors

401 Unauthorized

{
  "error": "Unauthorized"
}

Cause: Missing or invalid API key.

Solution: Include a valid API key in the Authorization header.

403 Forbidden

{
  "error": "Forbidden"
}

Cause: Insufficient permissions. Generating recommendations requires ADMIN, MANAGER, or PLANNER role.

Solution: Ensure your API key has the required permissions.

400 Bad Request

{
  "error": "Invalid request",
  "details": {
    "locationId": ["Location not found"]
  }
}

Cause: Invalid request parameters.

Solution: Review the request body and ensure all parameters are valid.

404 Not Found

{
  "error": "Recommendation not found"
}

Cause: The requested recommendation doesn’t exist or isn’t accessible.

Solution: Verify the recommendation ID and ensure you have access to it.

Query Parameters

List Recommendations

• status: Filter by status (PENDING, APPROVED, EXECUTED, REJECTED, EXPIRED)
• priority: Filter by priority (URGENT, HIGH, MEDIUM, LOW)
• productMasterId: Filter by product
• sourceLocationId: Filter by source location
• destLocationId: Filter by destination location
• validOnly: Return only valid recommendations (boolean)
• limit: Page size (default: 50, max: 100)
• offset: Offset for pagination (default: 0)

Generate Recommendations

• locationId: Generate for specific location (optional)
• productMasterId: Generate for specific product (optional)
• minStockDifferencePct: Minimum stock difference percentage (0-1)
• requirePositiveROI: Only generate recommendations with positive ROI (boolean)
• unitMargin: Profit margin per unit for ROI calculation

Request/Response Schemas

Transfer Recommendation

{
  id: string;
  productMasterId: string;
  sourceLocationId: string;
  destLocationId: string;
  quantity: number;
  priority: "URGENT" | "HIGH" | "MEDIUM" | "LOW";
  status: "PENDING" | "APPROVED" | "EXECUTED" | "REJECTED" | "EXPIRED";
  reason: string;
  estimatedROI?: number;
  createdAt: string; // ISO datetime
  approvedAt?: string; // ISO datetime
  executedAt?: string; // ISO datetime
}

Generate Recommendations Request

{
  locationId?: string;
  productMasterId?: string;
  minStockDifferencePct?: number; // 0-1
  requirePositiveROI?: boolean;
  unitMargin?: number; // Positive number
}

Approve/Reject Request

{
  comment?: string;
}

---

Related Pages

• API Overview
• Authentication
• Common Errors

---

Permissions & Roles

Transfer API access requires appropriate permissions:

• View: ADMIN, MANAGER, PLANNER, VIEWER roles
• Generate: ADMIN, MANAGER, PLANNER roles
• Approve/Execute: ADMIN, MANAGER roles