API-Dokumentation

Ship-ify API-Referenz

Vollständige Anleitung zur Integration der Ship-ify Verpackungsoptimierungs-API in Ihre Anwendungen.

Übersicht

Die Ship-ify API bietet 3D-Bin-Packing-Optimierung für E-Commerce-Sendungen. Bei gegebenen verfügbaren Kartongrößen und zu versendenden Artikeln berechnet die API die optimale Verpackungskonfiguration, um Versandkosten zu minimieren und gleichzeitig die Kartonauslastung zu maximieren.

Schnelle Optimierung

Ergebnisse in Millisekunden mit fortschrittlichen Algorithmen

3D-Verpackung

Echte 3D-Bin-Verpackung mit Rotationsunterstützung

Gewichtsbeschränkungen

Berücksichtigt Gewichtsgrenzen für jeden Kartontyp

Visualisierung

3D-HTML-Visualisierung (Pro & Enterprise)

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mit einem API-Schlüssel. Fügen Sie Ihren API-Schlüssel in die Anfrage-Header ein:

Authorization: Bearer YOUR_API_KEY

Important: Halten Sie Ihre API-Schlüssel sicher. Legen Sie sie niemals im clientseitigen Code oder in öffentlichen Repositories offen.

Sie können API-Schlüssel von Ihrem Dashboard.

Endpunkte

POST/api/v1/shipping-optimize

Optimieren Sie die Verpackung für eine Reihe von Artikeln in verfügbare Kartons.

Anfragekörper

JSON-Objekt mit boxes, items und options (siehe Anfrageformat)

GET/api/v1/shipping-optimize

Rufen Sie API-Funktionen, Nutzungsstatistiken und Beispielanfragen für Ihre Stufe ab.

Antwort

JSON-Objekt mit Stufenfähigkeiten, Kontingentinfo und Nutzungsstatistiken

Karton-Sets

Karton-Sets ermöglichen es Ihnen, Kartonkonfigurationen über API-Anfragen hinweg zu speichern und wiederzuverwenden. Anstatt das vollständige boxes-Array mit jeder Anfrage zu senden, können Sie ein gespeichertes Set über seinen eindeutigen Schlüssel referenzieren.

Tip: Erstellen Sie separate Karton-Sets für verschiedene Versandszenarien, wie Standard-Wellpappe vs. isolierte Kartons für temperaturempfindliche Artikel.

Karton-Sets verwalten

Erstellen und verwalten Sie Ihre Karton-Sets über das Karton-Sets-Dashboard. Jedes Set erhält einen eindeutigen Schlüssel wie bs_abc123xyz456.

Verwendung von Karton-Sets in Anfragen

Verwenden Sie boxSetKey anstelle des boxes-Arrays:

{
  "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"
  }
}

Karton-Set-Limits nach Stufe

Stufe	Max Sets
Free	1 (max 10 boxes)
Basic	2 (max 20 boxes each)
Pro	5 (max 50 boxes each)
Enterprise	50 (max 100 boxes each)

Anfrageformat

Der POST-Anfragekörper muss entweder boxes oder boxSetKey enthalten, plus items, und optional options.

Box-Objekt

Feld	Typ	Erforderlich	Beschreibung
id	string	Yes	Eindeutige Kennung für den Kartontyp
name	string	No	Lesbarer Name
dimensions	object	Yes	`{ length, width, height }` in Ihrer bevorzugten Einheit
weightCapacity	number	No	Strukturelle Gewichtsgrenze des Kartons - maximales Gewicht, das das Kartonmaterial physisch tragen kann
cost	number	No	Kosten pro Karton für die Optimierung

Item-Objekt

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
fragilityLevel	number	No	Zerbrechlichkeitsstufe von 0 (robust) bis 5 (extrem zerbrechlich). Wird von shipify-physics für Stapelentscheidungen verwendet. (Nur Pro+)
maxTopLoad	number	No	Maximales Gewicht, das dieser Artikel oben tragen kann. Wird von shipify-physics zur Durchsetzung von Tragfähigkeitsgrenzen verwendet. (Nur Pro+)

Options-Objekt

Feld	Typ	Standard	Beschreibung
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 (Basic+ 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.

Stapelbestellungen

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, "quantity": 2 }
      ]
    },
    {
      "orderId": "ORD-002",
      "items": [
        { "id": "item-2", "name": "Laptop", "dimensions": { "length": 14, "width": 10, "height": 2 }, "weight": 4.5, "quantity": 1 },
        { "id": "item-3", "name": "Charger", "dimensions": { "length": 4, "width": 3, "height": 2 }, "weight": 0.3, "quantity": 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.

Antwortformat

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.000Z

Algorithmen

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.

shipify-physicsAll Tiers

Physics-aware packing algorithm that prioritizes heavier items at the bottom for stability, respects fragility levels (0-5), enforces load capacity limits, and validates center of gravity balance. Includes support area validation (70% minimum) and rotation constraints for fragile items. Advanced features (fragilityLevel, maxTopLoad) require Pro or Enterprise tier.

Abonnementstufen

Choose the plan that fits your needs. FREE tier includes shipify-ultra and shipify-physics algorithms.

Feature	Free ($0)	Basic ($5/mo)	Pro ($20/mo)	Enterprise ($80/mo)
Items/Month	1,000	5,000	25,000	125,000
Max Items per Request	10	25	100	1,000
Max Box Types per Request	10	20	50	100
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	2 (shipify-ultra, physics)	6	8 (+max-rects, shipify-fit)	All 8
Overage Rate (per 1000 items)	$2.00	$1.50	$1.20	$1.00

Algorithm Availability by Tier

FREE: shipify-ultra, shipify-physics
BASIC: FREE + first-fit, best-fit, guillotine, shipify-max
PRO: All BASIC algorithms + max-rects, shipify-fit
ENTERPRISE: All 8 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 limit
X-RateLimit-Remaining: Items remaining after this request
X-RateLimit-Reset: When your quota resets (1st of next month)
X-Items-Used: Total items used this month

Fehlercodes

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

Beispiele

Beispielanfrage

{
  "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
  }
}

Beispielantwort

{
  "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-Beispiel

curl -X POST https://ship-ify.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 },
        "quantity": 1
      }
    ]
  }'

Jetzt ausprobieren!

Testen Sie die API interaktiv auf unserer Startseite mit dem integrierten API-Tester.