Better Data

API Reference

Transfers API

Edit this page

Transfers API

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

Scope: Workspace-scoped — requires authenticated organization context and valid credentials for that workspace.

Authentication

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

1Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Base URL

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

Headers

All requests must include:

1Content-Type: application/json
2Authorization: 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

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

Response:

1{
2  "recommendations": [
3    {
4      "id": "rec_123",
5      "productMasterId": "prod_123",
6      "sourceLocationId": "loc_456",
7      "destLocationId": "loc_789",
8      "quantity": 50,
9      "priority": "URGENT",
10      "status": "PENDING",
11      "reason": "Stock imbalance detected",
12      "estimatedROI": 0.15,
13      "createdAt": "2024-03-01T00:00:00Z"
14    }
15  ],
16  "total": 25,
17  "limit": 50,
18  "offset": 0
19}

Generate Transfer Recommendations

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

Response:

1{
2  "success": true,
3  "created": 15,
4  "recommendations": [
5    {
6      "id": "rec_456",
7      "productMasterId": "prod_789",
8      "sourceLocationId": "loc_123",
9      "destLocationId": "loc_456",
10      "quantity": 25,
11      "priority": "HIGH",
12      "status": "PENDING",
13      "reason": "High stock at source, low stock at destination",
14      "estimatedROI": 0.12
15    }
16  ]
17}

Approve Transfer Recommendation

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

Response:

1{
2  "success": true,
3  "recommendation": {
4    "id": "rec_123",
5    "status": "APPROVED",
6    "approvedAt": "2024-03-01T12:00:00Z",
7    "approvedBy": "user_123"
8  }
9}

Common Errors

401 Unauthorized

1{
2  "error": "Unauthorized"
3}

Cause: Missing or invalid API key.

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

403 Forbidden

1{
2  "error": "Forbidden"
3}

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

Solution: Ensure your API key has the required permissions.

400 Bad Request

1{
2  "error": "Invalid request",
3  "details": {
4    "locationId": ["Location not found"]
5  }
6}

Cause: Invalid request parameters.

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

404 Not Found

1{
2  "error": "Recommendation not found"
3}

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

1{
2  id: string;
3  productMasterId: string;
4  sourceLocationId: string;
5  destLocationId: string;
6  quantity: number;
7  priority: "URGENT" | "HIGH" | "MEDIUM" | "LOW";
8  status: "PENDING" | "APPROVED" | "EXECUTED" | "REJECTED" | "EXPIRED";
9  reason: string;
10  estimatedROI?: number;
11  createdAt: string; "cmt">// ISO datetime
12  approvedAt?: string; "cmt">// ISO datetime
13  executedAt?: string; "cmt">// ISO datetime
14}

Generate Recommendations Request

1{
2  locationId?: string;
3  productMasterId?: string;
4  minStockDifferencePct?: number; "cmt">// 0-1
5  requirePositiveROI?: boolean;
6  unitMargin?: number; "cmt">// Positive number
7}

Approve/Reject Request

1{
2  comment?: string;
3}

Permissions & Roles

Transfer API access requires appropriate permissions:

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

Recommendations

Scope: Workspace-scoped — requires authenticated organization context and valid credentials for that workspace.

Endpoints

List Recommendations

GET /api/transfers/recommendations

See the OpenAPI bundle for endpoint-level details.

Get Recommendation

GET /api/transfers/recommendations/{id}

See the OpenAPI bundle for endpoint-level details.

Pending Recommendations

GET /api/transfers/recommendations/pending

See the OpenAPI bundle for endpoint-level details.

Permissions & Roles

Viewing transfer recommendations requires standard user permissions.

Execute

Scope: Workspace-scoped — requires authenticated organization context and valid credentials for that workspace.

Endpoints

Execute Transfer

POST /api/transfers/recommendations/{id}/execute

See the OpenAPI bundle for endpoint-level details.

Permissions & Roles

Executing transfers requires inventory management permissions.

Approve / reject

Scope: Workspace-scoped — requires authenticated organization context and valid credentials for that workspace.

Endpoints

Approve Transfer

POST /api/transfers/recommendations/{id}/approve

See the OpenAPI bundle for endpoint-level details.

Reject Transfer

POST /api/transfers/recommendations/{id}/reject

See the OpenAPI bundle for endpoint-level details.

Permissions & Roles

Approving and rejecting transfers requires inventory management permissions.