> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  **Scope**: Tenant-scoped; requires authenticated org context\
  **Availability**: Not available in SuperAdmin
</Note>

## Authentication

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

```
Authorization: Bearer YOUR_API_KEY
```

See [Authentication](/api-reference/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

{/* this block is generated; do not edit by hand */}

| 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

```bash theme={null}
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:**

```json theme={null}
{
  "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

```bash theme={null}
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:**

```json theme={null}
{
  "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

```bash theme={null}
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:**

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

## Common Errors

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized"
}
```

**Cause**: Missing or invalid API key.

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

### 403 Forbidden

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```typescript theme={null}
{
  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

```typescript theme={null}
{
  locationId?: string;
  productMasterId?: string;
  minStockDifferencePct?: number; // 0-1
  requirePositiveROI?: boolean;
  unitMargin?: number; // Positive number
}
```

### Approve/Reject Request

```typescript theme={null}
{
  comment?: string;
}
```

***

## Related Pages

* [API Overview](/api-reference/overview)
* [Authentication](/api-reference/authentication)
* [Common Errors](/api-reference/errors)

***

## Permissions & Roles

<Tip>
  Transfer API access requires appropriate permissions:

  * **View**: `ADMIN`, `MANAGER`, `PLANNER`, `VIEWER` roles
  * **Generate**: `ADMIN`, `MANAGER`, `PLANNER` roles
  * **Approve/Execute**: `ADMIN`, `MANAGER` roles
</Tip>