Ship-ify API Reference
Complete guide to integrating the Ship-ify packing optimization API into your applications.
Overview
The Ship-ify API provides 3D bin packing optimization for e-commerce shipments. Given a set of available box sizes and items to ship, the API calculates the optimal packing configuration to minimize shipping costs while maximizing box utilization.
Fast Optimization
Results in milliseconds with advanced algorithms
3D Packing
True 3D bin packing with rotation support
Weight Constraints
Respects weight limits for each box type
Visualization
3D HTML visualization (Pro & Enterprise)
Authentication
All API requests require authentication using an API key. Include your API key in the request headers:
Authorization: Bearer YOUR_API_KEYImportant: Keep your API keys secure. Never expose them in client-side code or public repositories.
You can generate API keys from your dashboard.
Endpoints
/api/v1/shipping-optimizeOptimize packing for a set of items into available boxes.
Request Body
JSON object containing boxes, items, and options (see Request Format)
/api/v1/shipping-optimizeRetrieve API capabilities, usage statistics, and example requests for your tier.
Response
JSON object with tier capabilities, quota info, and usage stats
Box Sets
Box Sets allow you to save and reuse box configurations across API requests. Instead of sending the full boxes array with every request, you can reference a saved set by its unique key.
Tip: Create separate box sets for different shipping scenarios, such as standard cardboard boxes vs. insulated boxes for temperature-sensitive items.
Managing Box Sets
Create and manage your box sets from the Box Sets dashboard. Each set gets a unique key like bs_abc123xyz456.
Using Box Sets in Requests
Use boxSetKey instead of the boxes array:
{
"boxSetKey": "bs_abc123xyz456",
"items": [
{
"id": "item-001",
"name": "Product A",
"dimensions": { "length": 4, "width": 3, "height": 2 },
"weight": 1.5,
"quantity": 2
}
],
"options": {
"algorithm": "shipify-ultra"
}
}Box Set Limits by Tier
| Tier | Max Box Sets |
|---|---|
| Free | 3 |
| Basic | 10 |
| Pro | 50 |
| Enterprise | Unlimited |
Request Format
The POST request body must include either boxes or boxSetKey, plus items, and optionally options.
Box Object
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Unique identifier for the box type |
| name | string | No | Human-readable name |
| dimensions | object | Yes | { length, width, height } in your preferred unit |
| weightCapacity | number | No | Box structural weight limit - max weight the box material can physically hold |
| cost | number | No | Cost per box for optimization |
Item Object
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Unique identifier for the item |
| name | string | No | Human-readable name |
| dimensions | object | Yes | { length, width, height } in your preferred unit |
| weight | number | No | Item weight for constraint checking |
| quantity | number | No | Number of this item to pack (default: 1) |
| fragile | boolean | No | Mark as fragile for special handling |
| keepUpright | boolean | No | Prevent vertical rotation |
Options Object
| Field | Type | Default | Description |
|---|---|---|---|
| algorithm | string | "shipify-ultra" | Packing algorithm (see Algorithms section) |
| allowRotation | boolean | true | Allow items to be rotated for better fit |
| prioritize | string | "space" | "space" | "cost" | "speed" | "consolidation" |
| enableVisualization | boolean | false | Include 3D HTML visualization (Pro+ only) |
| maxShipmentWeight | number | - | Carrier weight limit - shipments above this threshold incur overweight fees |
| oversizedItemHandling | string | "unpacked" | "custom-box" | "unpacked" - How to handle items larger than any available box |
| overweightItemHandling | string | "allow" | "allow" | "unpacked" - How to handle items heavier than maxShipmentWeight (defaults to "allow" when maxShipmentWeight is set) |
Understanding Weight Constraints
The API supports two distinct types of weight constraints:
Box Structural Limit (weightCapacity)
Set on each box type. This represents the maximum weight the box material can physically hold without breaking. The optimizer will not place items that would exceed this structural limit.
"boxes": [{ "id": "medium", "weightCapacity": 25, ... }]Carrier Shipment Limit (maxShipmentWeight)
Set in options. This represents the carrier threshold above which overweight fees apply. All shipments will be optimized to stay under this limit regardless of box capacity. When this option is set, all items must have a weight property defined.
"options": { "maxShipmentWeight": 50 }Overweight Item Handling (overweightItemHandling)
When a single item exceeds the maxShipmentWeight, this option controls how it's handled:
"allow"(default): Item is allowed to ship alone in a box, weight limit waived for this shipment"unpacked": Item is placed in the unpackedItems array with reason
"options": { "maxShipmentWeight": 50, "overweightItemHandling": "unpacked" }Both constraints are enforced simultaneously. A shipment must satisfy both the box structural capacity and the carrier weight limit.
Batch Orders
Process multiple orders in a single API request. Instead of sending individual items, you can send an array of orders, each with its own items. The API will optimize packing for each order independently and return consolidated results.
Availability: All tiers
Batch order processing is available for all subscription tiers with the same limits.
Batch Limits
| Limit Type | Value |
|---|---|
| Max Orders per Batch | 50 |
| Max Items per Order | 100 |
| Max Total Items per Batch | 500 |
Batch Request Format
Use the orders array instead of items. Each order must have an orderId and its own items array.
{
"boxes": [
{ "id": "small", "name": "Small Box", "dimensions": { "length": 10, "width": 8, "height": 6 }, "cost": 2.50 },
{ "id": "medium", "name": "Medium Box", "dimensions": { "length": 14, "width": 12, "height": 10 }, "cost": 4.00 }
],
"orders": [
{
"orderId": "ORD-001",
"items": [
{ "id": "item-1", "name": "Book", "dimensions": { "length": 9, "width": 6, "height": 1.5 }, "weight": 1.2 }
]
},
{
"orderId": "ORD-002",
"items": [
{ "id": "item-2", "name": "Laptop", "dimensions": { "length": 14, "width": 10, "height": 2 }, "weight": 4.5 },
{ "id": "item-3", "name": "Charger", "dimensions": { "length": 4, "width": 3, "height": 2 }, "weight": 0.3 }
]
}
],
"options": {
"algorithm": "shipify-ultra"
}
}Batch Response Format
The response includes results for each order plus an overall summary.
{
"success": true,
"batch": true,
"results": [
{
"orderId": "ORD-001",
"success": true,
"data": {
"shipments": [...],
"unpackedItems": [],
"summary": { "totalShipments": 1, "totalCost": 2.50, ... }
}
},
{
"orderId": "ORD-002",
"success": true,
"data": {
"shipments": [...],
"unpackedItems": [],
"summary": { "totalShipments": 1, "totalCost": 4.00, ... }
}
}
],
"summary": {
"totalOrders": 2,
"successfulOrders": 2,
"failedOrders": 0,
"totalBoxesUsed": 2,
"totalCost": 6.50,
"averageUtilization": 42.5,
"totalItemsPacked": 3,
"totalItemsUnpacked": 0
},
"metadata": {
"algorithm": "shipify-ultra",
"executionTime": "45ms",
"timestamp": "2025-12-06T12:00:00.000Z"
}
}Backward Compatibility
The original single-order format using items array continues to work. Batch processing is only triggered when the orders array is present.
Response Format
Successful responses include shipment details, packing statistics, and metadata.
Response Structure
| Field | Description |
|---|---|
| success | Boolean indicating request success |
| data.shipments | Array of shipment objects with packed items |
| data.unpackedItems | Items that couldn't fit in any box |
| data.summary | Aggregated statistics (total cost, utilization, etc.) |
| data.suggestions | Optimization suggestions |
| metadata | Algorithm used, execution time, tier info |
| visualizationHtml | 3D HTML visualization (Pro+ only) |
Box Structure in Shipments
Each shipment contains a box object with the following fields:
| Field | Type | Description |
|---|---|---|
| id | string | Box ID (from your submitted boxes, or "custom-*" for oversized items) |
| name | string | Box name (or "Custom Box" for oversized items) |
| dimensions | object | { length, width, height } of the box |
| cost | number | Box cost (optional, 0 for custom boxes) |
| type | string | "custom" when oversizedItemHandling is "custom-box" (only present for custom boxes) |
Packed Items Structure
Each packed item in a shipment includes the following fields:
| Field | Type | Description |
|---|---|---|
| itemId | string | Original item ID as submitted in the request |
| itemIndex | number | Index within quantity expansion (0, 1, 2, ...). For items with quantity > 1, each instance gets a unique index. |
| position | object | { x, y, z } coordinates of item placement in the box |
| rotation | object | Axis mapping showing how item was rotated to fit |
| rotatedDimensions | object | { length, width, height } after rotation applied |
Rate Limit Headers
Every response includes rate limit information:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 985
X-RateLimit-Reset: 2025-11-30T00:00:00.000ZAlgorithms
Choose the algorithm that best fits your use case. Algorithm availability depends on your subscription tier.
first-fitBasic+Fast, simple algorithm that places items in the first available space. Best for speed-critical applications.
best-fitBasic+Finds the best fitting space for each item, improving utilization over first-fit.
guillotineBasic+Divides space into rectangles for efficient 2D packing. Good balance of speed and utilization.
max-rectsPro+Advanced algorithm maintaining multiple free rectangles for optimal packing.
shipify-ultraAll Tiers (Default)Our smartest algorithm, optimized for both binning (grouping items into separate shipments) and packing (placing items into the smallest possible box). Uses look-ahead optimization, post-pack consolidation, and multi-pass refinement to minimize total boxes and maximize space utilization. Best for most use cases.
shipify-fitPro+Combines global box selection strategy with fast 3D placement. Uses O(items × boxes × positions) complexity for efficient packing with excellent results.
shipify-maxBasic+Weight-based grouping algorithm that groups items by order, splits bundles exceeding weight limits, consolidates small bundles, and validates each bundle with 3D packing. Ideal for multi-order shipments where weight-based grouping is preferred.
Subscription Tiers
Choose the plan that fits your needs. FREE tier includes shipify-ultra algorithm.
| Feature | Free ($0) | Basic ($5/mo) | Pro ($20/mo) | Enterprise ($80/mo) |
|---|---|---|---|---|
| Items/Month | 1,000 | 5,000 | 25,000 | 125,000 |
| Max Box Types | 30 | 40 | 50 | 200 |
| API Keys | 1 | 1 | 5 | 10 |
| Batch Orders (max/items/total) | 50/100/500 | 50/100/500 | 50/100/500 | 50/100/500 |
| 3D Visualization | - | ✓ | ✓ | ✓ |
| Algorithms | 1 (shipify-ultra) | 5 | 7 (+max-rects, shipify-fit) | All 7 |
| Overage Rate (per 1000 items) | $2.00 | $1.50 | $1.20 | $1.00 |
Algorithm Availability by Tier
- FREE: shipify-ultra
- BASIC: shipify-ultra + first-fit, best-fit, guillotine, shipify-max
- PRO: All BASIC algorithms + max-rects, shipify-fit
- ENTERPRISE: All 7 algorithms
Rate Limits
Why We Count Items, Not API Requests
Batching multiple orders into a single API call is more efficient for everyone. Charging per item optimized aligns with our CPU costs and encourages you to batch orders for maximum efficiency. This means you can send 100 orders in one batch request and pay the same as 100 individual requests with one order each.
Usage limits are based on items processed per month (counting item quantities). Limits reset on the 1st of each month. When you exceed your limit, the API returns a 429 status code with details about your usage.
| Tier | Monthly Item Limit | Overage Rate |
|---|---|---|
| FREE | 1,000 items | $2.00 / 1,000 items |
| BASIC | 5,000 items | $1.50 / 1,000 items |
| PRO | 25,000 items | $1.20 / 1,000 items |
| ENTERPRISE | 125,000 items | $1.00 / 1,000 items |
Rate Limit Response
{
"error": "Monthly item limit exceeded",
"message": "This request would use 50 items, but you only have 25 items remaining in your monthly quota of 1000 items.",
"itemsRequested": 50,
"itemsRemaining": 25,
"monthlyLimit": 1000,
"resetAt": "2026-02-01T00:00:00.000Z"
}Response Headers
Every API response includes usage headers:
X-RateLimit-Limit: Your monthly item limitX-RateLimit-Remaining: Items remaining after this requestX-RateLimit-Reset: When your quota resets (1st of next month)X-Items-Used: Total items used this month
Error Codes
| Status | Error | Description |
|---|---|---|
| 400 | Invalid request | Missing or malformed boxes/items |
| 401 | Authentication failed | Invalid or missing API key |
| 403 | Feature not available | Algorithm or feature not in your tier |
| 403 | Limit exceeded | Too many items or box types for your tier |
| 429 | Monthly item limit exceeded | Monthly item quota exhausted |
| 500 | Internal server error | Server-side error, please retry |
Examples
Example Request
{
"boxes": [
{
"id": "b1-box",
"name": "Box B1",
"dimensions": {
"length": 7,
"width": 7,
"height": 12
},
"weightCapacity": 25,
"cost": 1.18
},
{
"id": "b3-box",
"name": "Box B3",
"dimensions": {
"length": 11,
"width": 10,
"height": 14
},
"weightCapacity": 35,
"cost": 2.11
},
{
"id": "b7-box",
"name": "Box B7",
"dimensions": {
"length": 20,
"width": 16,
"height": 18
},
"weightCapacity": 55,
"cost": 3.98
}
],
"items": [
{
"id": "BOOK-001",
"name": "Hardcover Book",
"dimensions": {
"length": 9.5,
"width": 7.5,
"height": 1.5
},
"weight": 1.8,
"quantity": 2
},
{
"id": "LAPTOP-COMP",
"name": "Laptop Computer",
"dimensions": {
"length": 18,
"width": 11,
"height": 4.5
},
"weight": 6.8,
"quantity": 1
}
],
"options": {
"algorithm": "shipify-ultra",
"allowRotation": true,
"prioritize": "space",
"enableVisualization": true
}
}Example Response
{
"success": true,
"data": {
"shipments": [
{
"box": {
"id": "b7-box",
"name": "Box B7",
"dimensions": {
"length": 20,
"width": 16,
"height": 18
},
"cost": 3.98
},
"packedItems": [
{
"itemId": "BOOK-001",
"itemIndex": 0,
"position": {
"x": 0,
"y": 0,
"z": 0
},
"rotation": {
"lengthAxis": "x",
"widthAxis": "y",
"heightAxis": "z"
},
"rotatedDimensions": {
"length": 9.5,
"width": 7.5,
"height": 1.5
}
},
{
"itemId": "BOOK-001",
"itemIndex": 1,
"position": {
"x": 9.5,
"y": 0,
"z": 0
},
"rotation": {
"lengthAxis": "x",
"widthAxis": "y",
"heightAxis": "z"
},
"rotatedDimensions": {
"length": 9.5,
"width": 7.5,
"height": 1.5
}
},
{
"itemId": "LAPTOP-COMP",
"itemIndex": 0,
"position": {
"x": 0,
"y": 0,
"z": 1.5
},
"rotation": {
"lengthAxis": "x",
"widthAxis": "y",
"heightAxis": "z"
},
"rotatedDimensions": {
"length": 18,
"width": 11,
"height": 4.5
}
}
],
"utilization": {
"volume": 18.2,
"weight": 18.9
},
"totalWeight": 10.4
}
],
"unpackedItems": [],
"summary": {
"totalShipments": 1,
"totalCost": 3.98,
"averageUtilization": 18.2,
"packingEfficiency": 18,
"itemsSuccessfullyPacked": 3,
"itemsUnpacked": 0
},
"suggestions": [
"Shipify-Ultra algorithm: Enhanced with look-ahead and consolidation"
]
},
"metadata": {
"algorithm": "shipify-ultra",
"executionTime": "32ms",
"timestamp": "2025-12-06T12:00:00.000Z",
"tier": "FREE"
}
}cURL Example
curl -X POST https://your-domain.com/api/v1/shipping-optimize \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"boxes": [
{
"id": "small-box",
"dimensions": { "length": 10, "width": 8, "height": 6 }
}
],
"items": [
{
"id": "item-1",
"dimensions": { "length": 4, "width": 3, "height": 2 }
}
]
}'