Better Data

Guides

Internal Transfer Workflow

Edit this page

Internal Transfer Workflow

This guide shows you how to create transfer recommendations, approve them, and execute the transfers.

Prerequisites

  • API Key: Valid API key with appropriate permissions:
    • transfers.read for viewing recommendations
    • transfers.write for generating recommendations
    • transfers.approve for approving recommendations
    • transfers.execute for executing transfers
  • Organization Access: Access to your organization's transfer features
  • Location IDs: Source and destination location IDs

Step-by-Step Guide

Step 1: Generate Transfer Recommendations

Generate transfer recommendations based on stock imbalances.

Request:

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": 5,
4  "recommendations": [
5    {
6      "id": "rec_123",
7      "productMasterId": "prod_123",
8      "sourceLocationId": "loc_123",
9      "destLocationId": "loc_456",
10      "quantity": 50,
11      "priority": "HIGH",
12      "status": "PENDING",
13      "reason": "High stock at source (200 units), low stock at destination (20 units)",
14      "estimatedROI": 0.15,
15      "createdAt": "2024-03-01T00:00:00Z"
16    }
17  ]
18}

Notes:

  • Min Stock Difference: Minimum percentage difference to trigger recommendation (0-1)
  • Positive ROI: Only generate recommendations with positive return on investment
  • Unit Margin: Profit margin per unit for ROI calculation
  • Priority: Automatically calculated based on stock levels and urgency

Step 2: List Pending Recommendations

Retrieve pending recommendations that need approval.

Request:

1curl -X GET "https://app.betterdata.co/api/transfers/recommendations/pending" \
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_123",
7      "destLocationId": "loc_456",
8      "quantity": 50,
9      "priority": "HIGH",
10      "status": "PENDING",
11      "reason": "High stock at source, low stock at destination",
12      "estimatedROI": 0.15,
13      "createdAt": "2024-03-01T00:00:00Z"
14    }
15  ],
16  "total": 5,
17  "limit": 50,
18  "offset": 0
19}

Alternative: Filter by Status

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

Step 3: Get Recommendation Details

Get detailed information about a specific recommendation.

Request:

1curl -X GET "https://app.betterdata.co/api/transfers/recommendations/rec_123" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json"

Response:

1{
2  "id": "rec_123",
3  "productMasterId": "prod_123",
4  "productName": "Product Name",
5  "sourceLocationId": "loc_123",
6  "sourceLocationName": "Main Warehouse",
7  "destLocationId": "loc_456",
8  "destLocationName": "Store Front",
9  "quantity": 50,
10  "priority": "HIGH",
11  "status": "PENDING",
12  "reason": "High stock at source (200 units), low stock at destination (20 units)",
13  "estimatedROI": 0.15,
14  "sourceStock": 200,
15  "destStock": 20,
16  "createdAt": "2024-03-01T00:00:00Z"
17}

Step 4: Approve Recommendation

Approve a transfer recommendation.

Request:

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    "comment": "Approved for immediate transfer"
9  }
10}

Notes:

  • Approval Required: Recommendations must be approved before execution
  • Comment Optional: Include a comment explaining approval decision
  • Role Required: Requires ADMIN or MANAGER role

Step 5: Execute Transfer

Execute an approved transfer recommendation.

Request:

1curl -X POST "https://app.betterdata.co/api/transfers/recommendations/rec_123/execute" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shipmentDate": "2024-03-02T00:00:00Z",
6    "expectedDeliveryDate": "2024-03-03T00:00:00Z",
7    "carrier": "Internal Transfer",
8    "trackingNumber": "TRANSFER-123"
9  }'

Response:

1{
2  "success": true,
3  "transfer": {
4    "id": "transfer_123",
5    "recommendationId": "rec_123",
6    "status": "EXECUTED",
7    "shipmentId": "ship_123",
8    "executedAt": "2024-03-01T12:30:00Z",
9    "executedBy": "user_123"
10  }
11}

Notes:

  • Status Check: Only APPROVED recommendations can be executed
  • Shipment Creation: Execution creates a shipment record
  • Inventory Update: Inventory is updated when shipment is received

Step 6: Reject Recommendation (Alternative)

If a recommendation shouldn't be executed, reject it.

Request:

1curl -X POST "https://app.betterdata.co/api/transfers/recommendations/rec_123/reject" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "comment": "Stock levels acceptable, no transfer needed"
6  }'

Response:

1{
2  "success": true,
3  "recommendation": {
4    "id": "rec_123",
5    "status": "REJECTED",
6    "rejectedAt": "2024-03-01T12:00:00Z",
7    "rejectedBy": "user_123",
8    "comment": "Stock levels acceptable, no transfer needed"
9  }
10}

Complete Example

Here's a complete workflow example:

1#!/bin/bash
2 
3API_KEY="YOUR_API_KEY"
4BASE_URL="https://app.betterdata.co/api"
5 
6# Step 1: Generate recommendations
7echo "Generating transfer recommendations..."
8RECOMMENDATIONS_RESPONSE=$(curl -s -X POST "${BASE_URL}/transfers/recommendations" \
9  -H "Authorization: Bearer ${API_KEY}" \
10  -H "Content-Type: application/json" \
11  -d '{
12    "minStockDifferencePct": 0.2,
13    "requirePositiveROI": true
14  }')
15 
16CREATED=$(echo $RECOMMENDATIONS_RESPONSE | jq -r '.created')
17echo "Created ${CREATED} recommendations"
18 
19# Step 2: Get pending recommendations
20echo "Fetching pending recommendations..."
21PENDING_RESPONSE=$(curl -s -X GET "${BASE_URL}/transfers/recommendations/pending" \
22  -H "Authorization: Bearer ${API_KEY}" \
23  -H "Content-Type: application/json")
24 
25# Step 3: Process each recommendation
26echo $PENDING_RESPONSE | jq -r '.recommendations[] | @json' | while read rec; do
27  REC_ID=$(echo $rec | jq -r '.id')
28  PRIORITY=$(echo $rec | jq -r '.priority')
29  QUANTITY=$(echo $rec | jq -r '.quantity')
30  
31  echo "Processing recommendation ${REC_ID} (Priority: ${PRIORITY}, Qty: ${QUANTITY})"
32  
33  # Step 4: Approve if high priority
34  if [ "$PRIORITY" = "URGENT" ] || [ "$PRIORITY" = "HIGH" ]; then
35    echo "  Approving recommendation..."
36    APPROVE_RESPONSE=$(curl -s -X POST "${BASE_URL}/transfers/recommendations/${REC_ID}/approve" \
37      -H "Authorization: Bearer ${API_KEY}" \
38      -H "Content-Type: application/json" \
39      -d '{
40        "comment": "Auto-approved high priority transfer"
41      }')
42    
43    # Step 5: Execute immediately
44    echo "  Executing transfer..."
45    EXECUTE_RESPONSE=$(curl -s -X POST "${BASE_URL}/transfers/recommendations/${REC_ID}/execute" \
46      -H "Authorization: Bearer ${API_KEY}" \
47      -H "Content-Type: application/json" \
48      -d '{
49        "carrier": "Internal Transfer"
50      }')
51    
52    TRANSFER_ID=$(echo $EXECUTE_RESPONSE | jq -r '.transfer.id')
53    echo "  Transfer executed: ${TRANSFER_ID}"
54  else
55    echo "  Skipping - not high priority"
56  fi
57done

Idempotency Notes

  • Generate Recommendations: Generating recommendations multiple times may create duplicates. Check for existing recommendations before generating.
  • Approve/Reject: Approving or rejecting a recommendation is idempotent - subsequent calls return the same result.
  • Execute: Executing a recommendation creates a transfer/shipment. Multiple executions will create multiple transfers (not idempotent). Check status before executing.

Pagination Notes

  • List Recommendations: Supports pagination with limit and offset (default: 50, max: 100).
  • Pending Recommendations: Returns all pending recommendations (may require pagination for large datasets).

Common Issues

Recommendations Not Generated

Symptom: No recommendations returned despite stock imbalances.

Solutions:

  1. Verify minStockDifferencePct threshold is appropriate
  2. Check that requirePositiveROI isn't filtering out valid recommendations
  3. Ensure source and destination locations have sufficient stock difference
  4. Verify locations are active and accessible

Cannot Approve Recommendation

Symptom: Error when trying to approve recommendation.

Solutions:

  1. Verify recommendation status is PENDING
  2. Check user has ADMIN or MANAGER role
  3. Ensure API key has transfers.approve permission
  4. Verify recommendation hasn't expired

Execution Fails

Symptom: Error when executing transfer.

Solutions:

  1. Verify recommendation status is APPROVED (not PENDING or REJECTED)
  2. Check source location has sufficient stock
  3. Ensure destination location is active
  4. Verify shipment date is in the future

Permissions & Roles