Skip to main content

​
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

MethodPathSummaryAuthStabilityPermissions
GET/api/inventory/transfersList inventory transferssessionstabletransfers.read
POST/api/inventory/transfersCreate inventory transfersessionstabletransfers.write
GET/api/inventory/transfers/[id]Get inventory transfersessionstabletransfers.read
POST/api/inventory/transfers/[id]Update inventory transfersessionstabletransfers.write
GET/api/inventory/transfers/binsGet transfer binssessionstabletransfers.read
GET/api/transfers/recommendationsList transfer recommendationssessionstabletransfers.read
POST/api/transfers/recommendationsGenerate new transfer recommendationssessionstabletransfers.write
GET/api/transfers/recommendations/[id]Get a specific recommendationsessionstabletransfers.read
POST/api/transfers/recommendations/[id]/approveApprove a transfer recommendationsessionstabletransfers.approve
POST/api/transfers/recommendations/[id]/executeExecute a transfer recommendationsessionstabletransfers.execute
POST/api/transfers/recommendations/[id]/rejectReject a transfer recommendationsessionstabletransfers.approve
GET/api/transfers/recommendations/pendingGet pending recommendationssessionstabletransfers.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;
}

​
Permissions & Roles

Transfer API access requires appropriate permissions:
  • View: ADMIN, MANAGER, PLANNER, VIEWER roles
  • Generate: ADMIN, MANAGER, PLANNER roles
  • Approve/Execute: ADMIN, MANAGER roles