Introduction
The TCS-i API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
https://api.tcs-innovations.comAuthentication
The TCS-i API uses API keys to authenticate requests. You can view and manage your API keys in your Customer Dashboard after subscribing via the Google Cloud Marketplace.
Authentication to the API is performed via the x-api-key HTTP header. All API requests must be made over HTTPS.
curl -X POST https://api.tcs-innovations.com/pack \
-H "Content-Type: application/json" \
-H "x-api-key: your_production_api_key_here"
/pack
Computes a highly optimized 3D packing solution (cartonization) based on your provided inventory items, available bins, and specific objective targets.
Request Body
Custom metadata dictionary to be passed along with the packing request.
The list of products to be packed. See the Item Data Model for property requirements.
Required for standard packing. Can be omitted if objective is minimise_bounding_box.
Defaults to minimise_bins. See Objectives model for full list.
Defines physics rules: rotation logic, fragility limits, center of gravity checks, and forbidden adjacencies.
Used when objective is set to minimise_total_cost. Defines shipping base rates, per-kg rates, and DIM divisors to evaluate the most cost-effective packaging.
{
"objective": "minimise_total_cost",
"items": [
{ "id": "I-001", "length": 2.0, "width": 4.0, "height": 4.0, "weight": 1.5, "label": "electronics", "is_cylinder": false },
{ "id": "I-002", "length": 5.0, "width": 5.0, "height": 2.0, "weight": 0.5, "label": "accessories", "is_cylinder": true }
],
"bins": [
{ "id": "B-001", "length": 10.0, "width": 10.0, "height": 10.0, "is_envelope": false, "fixed_cost": 2.0, "tare_weight": 0.2, "quantity": 2 }
],
"constraints": {
"rotation": true,
"fragility": ["I-001"],
"weight_distribution": {
"max_per_layer": 10.0,
"footprint": 5.0,
"center_of_gravity": true,
"min_support_ratio": 0.8
},
"forbidden_adjacency": [["electronics", "liquids"]],
"priority": ["I-001"]
},
"cost_model": {
"ship_base": 0.6,
"ship_rate_per_kg": 1.1,
"dim_divisor": 5000.0,
"dunnage_cost_per_volume": 0.05
}
}
{
"solution": {
"num_bins_used": 1,
"bins": [
{
"id": "B-001",
"length": 10.0, "width": 10.0, "height": 10.0,
"items": [
{
"id": "I-001",
"origin_dims": [2.0, 4.0, 4.0],
"rotation_instruction": "perm(0, 1, 2)",
"rotated_dims": [2.0, 4.0, 4.0],
"position": [0.0, 0.0, 0.0],
"is_cylinder": false
},
{
"id": "I-002",
"origin_dims": [5.0, 5.0, 2.0],
"rotation_instruction": "perm(0, 2, 1)",
"rotated_dims": [5.0, 2.0, 5.0],
"position": [2.0, 0.0, 0.0],
"is_cylinder": true
}
]
}
],
"packed_item_ids": ["I-001", "I-002"],
"unpacked_item_ids": []
}
}
Packing Data Models
/batch
Intelligently group pending orders into optimized picking batches. The macro-batching engine evaluates item locations, distance matrices, and order SLAs to generate the most efficient groupings, maximizing picker throughput while preventing SLA breaches.
Request Body
The current active pool of orders to evaluate for release.
Additional orders that can be pulled into the active pool to optimize routing.
A 2D dictionary mapping location IDs to other location IDs with their respective travel distances.
The destination ID where the batched items will be dropped off for packing.
The target number of orders to release in this batch. Defaults to 500.
Tuning parameters for the optimization algorithm. `sla_weight` (default 2.0) determines distance sacrifice for SLA, `age_weight` (default 0.1) prevents black-hole scenarios.
{
"pack_station_id": "PACK-ZONE-A",
"target_release_count": 2,
"sla_weight": 2.5,
"active_pool": [
{
"order_id": "ORD-5541",
"total_volume": 12.5,
"sla_priority": 4,
"age_minutes": 45.0,
"items": [
{ "item_id": "IPHONE-15", "location_id": "A-04-02" }
]
}
],
"candidate_pool": [
{
"order_id": "ORD-5542",
"total_volume": 5.0,
"sla_priority": 2,
"age_minutes": 10.0,
"items": [
{ "item_id": "AIRPODS", "location_id": "A-04-05" }
]
}
],
"distance_matrix": {
"A-04-02": { "A-04-05": 3.5, "PACK-ZONE-A": 40.0 },
"A-04-05": { "A-04-02": 3.5, "PACK-ZONE-A": 38.0 }
}
}
{
"released_order_ids": [
"ORD-5541",
"ORD-5542"
],
"route_footprint": [
"A-04-02",
"A-04-05",
"PACK-ZONE-A"
]
}
Batching Data Models
/pick
Transforms a grouped batch of orders into a highly optimized physical routing path. The algorithm considers warehouse topology, one-way aisles, and start/end positions to minimize picker travel distance and provide a sequenced step-by-step picking list.
Request Body
The unique identifier of the fulfillment center where the picking will take place.
The ID of the grouped batch (generated via the /batch endpoint) that needs to be routed.
The physical ID of where the picker begins their route (e.g., "ZONE-A-ENTRY").
The physical ID of where the picker must drop off the completed batch (e.g., "PACK-STATION-1").
The maximum number of discrete items the picking cart can physically hold.
{
"warehouse_id": "wh_uk_london_01",
"batch_id": "bat_8x7d6c5b4a",
"starting_location": "ZONE-A-ENTRY",
"ending_location": "PACK-STATION-1",
"cart_capacity": 40
}
{
"route_id": "rt_9988776655",
"batch_id": "bat_8x7d6c5b4a",
"estimated_time_seconds": 420,
"total_distance_meters": 115.5,
"pick_path": [
{
"step_sequence": 1,
"location_id": "A-04-02",
"action": "pick",
"items": [
{ "sku": "IPHONE-15-PRO", "quantity": 1, "order_ref": "ORD-5541" }
]
},
{
"step_sequence": 2,
"location_id": "A-04-05",
"action": "pick",
"items": [
{ "sku": "AIRPODS-PRO", "quantity": 2, "order_ref": "ORD-5542" }
]
},
{
"step_sequence": 3,
"location_id": "PACK-STATION-1",
"action": "dropoff",
"items": []
}
]
}
Picking Data Models
/ship
Rate-shops across your connected carrier network in real-time. By leveraging the exact 3D dimensions (DIM weight) and actual weight of your parcels, the engine instantly selects the lowest-cost shipping label that meets your requested delivery SLA.
Request Body
Your internal order or shipment ID. Passed back in the response and on webhooks.
The final delivery destination for the shipment.
Overrides the default fulfillment center address configured in your dashboard.
List of packages in this shipment, including dimensions and physical weights.
Filters rates to match the promised SLA (e.g., "next_day" or an exact integer like 3). Defaults to standard.
Global unit for weights. Accepts "kg" or "lb". Defaults to kg.
Global unit for dimensions. Accepts "cm" or "in". Defaults to cm.
Limits the algorithm to query specific pre-configured carrier accounts (e.g., "acc_dpd_uk").
{
"shipment_ref": "ORD-88192-A",
"destination_address": {
"name": "John Doe",
"street1": "10 Downing Street",
"city": "London",
"state": "Greater London",
"postcode": "SW1A 2AA",
"country": "GB"
},
"origin_address": {
"name": "London Hub",
"street1": "Unit 4, Prologis Park",
"city": "London",
"state": "Greater London",
"postcode": "UB7 9FN",
"country": "GB"
},
"parcels": [
{
"length": 30.0,
"width": 25.0,
"height": 20.0,
"weight": 3.2,
"declared_value": 45.00
}
],
"delivery_sla": "next_day",
"carrier_accounts": ["acc_dpd_uk", "acc_rmail"]
}
{
"shipment_id": "shp_9x8f7a6b5c4d3e2f1",
"shipment_ref": "ORD-88192-A",
"status": "label_created",
"selected_rate": {
"carrier": "DPD",
"service": "DPD Next Day Parcel",
"cost": 4.50,
"currency": "GBP",
"estimated_delivery_date": "2026-03-09T18:00:00Z"
},
"tracking_number": "15502938492",
"tracking_url": "https://track.dpd.co.uk/15502938492",
"label_format": "zpl",
"label_base64": "XlhB..."
}
Shipping Data Models
/slot
Sub-200ms Dynamic Slotting Engine with Smart Cascade & Fast-Track. Intercepts inbound WMS dock scans in real-time. Calculates global SKU velocity against rolling hourly picks to dynamically route items to the Golden, Silver, or Dead Zones.
Request Body
Details about the incoming item, including its rolling hourly pick history for velocity calculation.
Thresholds for zone classifications and multi-bin drain support rules.
The current home bin (if any) and available empty bins for the engine to consider.
{
"sku": {
"sku_id": "SKU-992-BLK",
"quantity_to_move": 120,
"unit_volume": 1.5,
"rolling_hourly_picks": [10, 15, 8, 45]
},
"warehouse_context": {
"golden_zone_velocity_threshold_per_hour": 30.0,
"silver_zone_velocity_threshold_per_hour": 15.0,
"multi_bin_drain_supported": true
},
"bin_options": {
"current_home_bin": {
"bin_id": "RES-09-02",
"zone": "Dead Zone",
"available_volume": 100.0,
"current_quantity_left": 50
},
"empty_bins": [
{
"bin_id": "A-04-12",
"zone": "Silver Zone",
"available_volume": 500.0,
"current_quantity_left": 0
}
]
}
}
{
"meta": {
"decision_code": "UPGRADE_CONSOLIDATE",
"status": 200
},
"allocations": [
{
"bin_id": "A-04-12",
"role": "new_primary",
"action": "putaway",
"inbound_putaway_qty": 120,
"sweep_in_qty": 50,
"sweep_out_qty": 0,
"total_expected_qty": 170
},
{
"bin_id": "RES-09-02",
"role": "old_home",
"action": "sweep_out",
"inbound_putaway_qty": 0,
"sweep_in_qty": 0,
"sweep_out_qty": 50,
"total_expected_qty": 0
}
],
"telemetry": {
"trend_classification": "FAST_TRACK_SILVER",
"calculated_hourly_rate": 22.6,
"golden_threshold_applied": 30.0
}
}