Bin Packer API Documentation

Add a Box

Cost: 0 credit(s) per call

Endpoint

POST /v1/binpacker/box

The Bin Packer API helps you simulate real-world packaging scenarios by automatically calculating the most efficient way to fit items into shipping cartons or containers. This will be useful for estimating fulfillment needs, testing packaging constraints, or building a custom shipping logic.

You can define your own box types (like “Small Box” or “Oversized Carton”) with size and weight limits, then submit a list of items to see how they’d be packed using the available boxes. The response gives you a breakdown of what fits where, which items don’t fit, and the total weight of each box. It’s a fast, flexible tool for anything from shipping calculators to warehouse logic.

Parameters

Header	In	Type	Required	Description
`Authorization`	header	string	Yes	API Key from your console.
`Content-Type`	header	string	Yes	Must be `application/json`.
name	body	string	Yes	Box name (≤ 15 chars, unique)
width	body	number (float)	Yes	0 < width < 10 000 — box inner width
height	body	number (float)	Yes	0 < height < 10 000
depth	body	number (float)	Yes	0 < depth < 10 000
max_weight	body	number (float)	No	0 ≤ max_weight < 10 000 (capacity)
box_weight	body	number (float)	No	0 ≤ box_weight < 10 000 (tare)
weight_units	body	string	No	e.g. `kg`, default `kg`
length_units	body	string	No	e.g. `cm`, default `cm`

JSON Response

{
  "success": true,
  "box_id": 42
}

Response Fields

Field	Type	Constraints / Notes	Example
`success`	boolean	`true` if successful	`true`
`box_id`	number	The ID of the box	40

Code Snippets

Code ready to go! Select one of your API keys to fill in the code

Note: You can also try it in our API playground



curl -X POST https://api.wyldapi.com/v1/binpacker/box \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Medium-Carton",
        "width": 50,
        "height": 33,
        "depth": 45,
        "max_weight": 100,
        "box_weight": 0.3,
        "length_units": "cm",
        "weight_units": "kg"
      }'



import requests
url = "https://api.wyldapi.com/v1/binpacker/box"
headers = {
    "Authorization": "Bearer <YOUR_TOKEN>",
    "Content-Type": "application/json"
}
payload = {
    "name": "Medium-Carton",
    "width": 50,
    "height": 33,
    "depth": 45,
    "max_weight": 100,
    "box_weight": 0.3,
    "length_units": "cm",
    "weight_units": "kg"
}

resp = requests.post(url, json=payload, headers=headers)
print(resp.status_code, resp.json())



<?php
$ch = curl_init('https://api.wyldapi.com/v1/binpacker/box');
$body = json_encode([
    'name'         => 'Medium-Carton',
    'width'        => 50,
    'height'       => 33,
    'depth'        => 45,
    'max_weight'   => 100,
    'box_weight'   => 0.3,
    'length_units' => 'cm',
    'weight_units' => 'kg'
]);

curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
        'Content-Type: application/json',
        'Content-Length: ' . strlen($body)
    ],
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP $httpCode\n$response\n";



const url = 'https://api.wyldapi.com/v1/binpacker/box';
const payload = {
  name: 'Medium-Carton',
  width: 50,
  height: 33,
  depth: 45,
  max_weight: 100,
  box_weight: 0.3,
  length_units: 'cm',
  weight_units: 'kg'
};

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_TOKEN>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
})
  .then(res => res.json().then(data => ({ status: res.status, body: data })))
  .then(console.log)
  .catch(console.error);



import axios from 'axios';

function addBox() {
  axios.post(
    'https://api.wyldapi.com/v1/binpacker/box',
    {
      name: 'Medium-Carton',
      width: 50,
      height: 33,
      depth: 45,
      max_weight: 100,
      box_weight: 0.3,
      length_units: 'cm',
      weight_units: 'kg'
    },
    {
      headers: { Authorization: 'Bearer <YOUR_TOKEN>' }
      
    }
  )
  .then(res => console.log(res.data))
  .catch(err => console.error(err.response?.data || err.message));
}

Delete a Registered Box

Cost: 0 credit(s) per call

Endpoint

DELETE /v1/binpacker/box

If you no longer need a box you've previously defined, you can remove it by sending a DELETE request to this endpoint. A box can only be deleted if it belongs to your account, and the box_id must be valid.

This is helpful when you’re cleaning up unused boxes or testing different configurations and want to start fresh.

You can get the box_id from the next call. You can optionally delete the the box inside the Box Sizes feature of the console

Parameters

Header	In	Type	Required	Description
`Authorization`	header	string	Yes	API Key from your console.
`Content-Type`	header	string	Yes	Must be `application/json`.
`box_id`	path	integer	Yes	Numeric identifier of the box returned by `POST /box` or `GET /boxes`.

JSON Response

{
  "success": true
}

Response Fields

Field	Type	Description
`success`	boolean	`true` – the box existed and was deleted. `false` – the box ID was not found, so nothing was removed.

Code Snippets

Code ready to go! Select one of your API keys to fill in the code

Note: You can also try it in our API playground



curl -X DELETE "https://api.wyldapi.com/v1/binpacker/box/42" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"



import requests

box_id = 42
url     = f"https://api.wyldapi.com/v1/binpacker/box/{box_id}"
headers = {"Authorization": "Bearer <YOUR_TOKEN>"}

resp = requests.delete(url, headers=headers, verify=False)
print(resp.status_code, resp.json())



<?php
$boxId = 42;
$ch = curl_init("https://api.wyldapi.com/v1/binpacker/box/$boxId");

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "DELETE",
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer <YOUR_TOKEN>",
        "Accept: application/json"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($ch);
$code     = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP $code\n$response\n";



const boxId = 42;

fetch(`https://api.wyldapi.com/v1/binpacker/box/${boxId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer <YOUR_TOKEN>',
    'Accept': 'application/json'
  }
})
  .then(res => res.json().then(data => ({ status: res.status, body: data })))
  .then(console.log)
  .catch(console.error);



import axios from 'axios';
import https from 'https';   // Node’s https agent for dev certificates

function deleteBox(boxId) {
  axios.delete(
    `https://api.wyldapi.com/v1/binpacker/box/${boxId}`,
    {
      headers: { Authorization: 'Bearer <YOUR_TOKEN>' }
    }
  )
  .then(res => console.log(res.data))
  .catch(err => console.error(err.response?.data || err.message));
}

// usage
deleteBox(42);

Get All Boxes

Cost: 0 credit(s) per call

Endpoint

GET /v1/binpacker/boxes

This endpoint lets you retrieve a list of all the boxes currently registered to your account. It’s useful if you need to check what definitions are available before packing, or if you're building a dashboard or settings view.

Each box returned includes its name, size, max capacity, and unit types. If no boxes have been created yet, the array will be empty.

Parameters

Header	In	Type	Required	Description
`Authorization`	header	string	Yes	API Key from your console.
`Content-Type`	header	string	Yes	Must be `application/json`.

JSON Response

{
  "success": true,
  "boxes": [
    {
      "id": 12,
      "name": "Medium-Carton",
      "width": 50,
      "height": 33,
      "depth": 45,
      "max_weight": 100,
      "box_weight": 0.3,
      "weight_units": "kg",
      "length_units": "cm"
    },
    {
      "id": 13,
      "name": "Small-Carton",
      "width": 30,
      "height": 20,
      "depth": 20,
      "max_weight": 40,
      "box_weight": 0.2,
      "weight_units": "kg",
      "length_units": "cm"
    }
  ]
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates whether the request was processed successfully (always `true` for HTTP 200 responses).
`boxes`	array <object>	List of the user’s saved box definitions. The array may be empty if no boxes exist.
`boxes[].id`	integer	Unique identifier of the box.
`boxes[].name`	string	Friendly name / SKU assigned when the box was created.
`boxes[].width`	number	Inside width in `length_units`.
`boxes[].height`	number	Inside height in `length_units`.
`boxes[].depth`	number	Inside depth in `length_units`.
`boxes[].max_weight`	number	Maximum load the box can carry, in `weight_units`.
`boxes[].box_weight`	number	Tare (empty) weight of the box.
`boxes[].weight_units`	string	Unit used for all weight values (e.g., `kg`, `lb`).
`boxes[].length_units`	string	Unit used for all dimension values (e.g., `cm`, `in`).

Code Snippets

Code ready to go! Select one of your API keys to fill in the code

Note: You can also try it in our API playground



curl -X GET "https://api.wyldapi.com/v1/binpacker/boxes" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"



import requests

url     = "https://api.wyldapi.com/v1/binpacker/boxes"
headers = {"Authorization": "Bearer <YOUR_TOKEN>"}

resp = requests.get(url, headers=headers, verify=False)
print(resp.status_code)
print(resp.json())



<?php
$ch = curl_init("https://api.wyldapi.com/v1/binpacker/boxes");

curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer <YOUR_TOKEN>",
        "Accept: application/json"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($ch);
$code     = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP $code\n$response\n";



fetch('https://api.wyldapi.com/v1/binpacker/boxes', {
  headers: {
    'Authorization': 'Bearer <YOUR_TOKEN>',
    'Accept': 'application/json'
  }
})
  .then(res => res.json().then(data => ({ status: res.status, body: data })))
  .then(console.log)
  .catch(console.error);



import axios from 'axios';
import https from 'https';  // Node agent for local dev (ignore cert)

function getBoxes() {
  axios.get(
    'https://api.wyldapi.com/v1/binpacker/boxes',
    {
      headers: { Authorization: 'Bearer <YOUR_TOKEN>' }
    }
  )
  .then(res => console.log(res.data))
  .catch(err => console.error(err.response?.data || err.message));
}

// call it, e.g. in useEffect or on button click
getBoxes();

Pack and Get Results

Cost: 1 credit(s) per call

Endpoint

POST /v1/binpacker/pack

This is the main endpoint you'll use to simulate packing items into the boxes you've registered. Just send a list of items with their dimensions and weights, and the API will calculate the best packing layout using your saved boxes.

The response will show which items fit into each box, which boxes were used, total box weights, and any items that couldn’t be packed due to space or weight limits.

Parameters

Header	In	Type	Required	Description
`Authorization`	header	string	Yes	API Key from your console.
`Content-Type`	header	string	Yes	Must be `application/json`.
name	body	string	Yes	Item identifier
width	body	number (float)	Yes	0 < width < 10 000
height	body	number (float)	Yes	0 < height < 10 000
depth	body	number (float)	Yes	0 < depth < 10 000
weight	body	number (float)	Yes	0 < weight
quantity	body	integer	Yes	1 ≤ quantity ≤ 10 000

JSON Response

{
  "packed": [
    {
      "name": "Large-Carton",
      "width": 50,
      "height": 33,
      "depth": 45,
      "length_units": "cm",
      "weight_units": "kg",
      "total_weight": 88.3,
      "items": [
        { "name": "Widget-A": "quantity": 5 },
        { "name": "Widget-D": "qnatity": 1 }
      ]
    },
    {
      "name": "Medium-Carton",
      "width": 30,
      "height": 33,
      "depth": 45,
      "length_units": "cm",
      "weight_units": "kg",
      "total_weight": 48.3,
      "items": [
        { "name": "Widget-A", "quantity": 2 },
        { "name": "Widget-B", "quantity": 4 }
      ]
    }
  ],
  "not_fit": [
    { "name": "Widget-C", "quantity": 1 }
  ],
  "request": "2 boxes packed - 1 didn't fit"
}

Response Fields

Field	Type	Description
`packed`	array <object>	List of boxes the service filled. Absent if `success` is `false`.
`packed[].name`	string	Box name (definition used).
`packed[].width`<br>`packed[].height`<br>`packed[].depth`	number	Inside dimensions of the box.
`packed[].length_units`<br>`packed[].weight_units`	string	Units for size and weight.
`packed[].total_weight`	number	Combined weight of the box plus all items it contains.
`packed[].items`	array <object>	Items placed inside this box.
`packed[].items[].name`	string	The name of the item passed to the API.
`packed[].items[].quantity`	string	The quantity of the item in this box.
`not_fit`	array <object>	Items that could not be placed in any box.
`not_fit[].name`	string	The name of the item passed to the API.
`not_fit[].quantity`	string	The quantity of this item that didn't fit.
`success`	boolean	Present only when the request fails validation (`false`).
`error`	string	Human-readable reason for failure (validation only).
`request`	string	Echo / summary string returned by the API.

Code Snippets

Code ready to go! Select one of your API keys to fill in the code

Note: You can also try it in our API playground



curl -X POST "https://api.wyldapi.com/v1/binpacker/pack" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "items": [
    { "name": "Widget-A", "width": 10, "height": 33, "depth": 45, "weight": 40, "quantity": 5 },
    { "name": "Gizmo-B",  "width": 20, "height": 15, "depth": 15, "weight": 12, "quantity": 3 }
  ]
}
JSON



import requests

url = "https://api.wyldapi.com/v1/binpacker/pack"
headers = {
    "Authorization": "Bearer <YOUR_TOKEN>",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {"name": "Widget-A", "width": 10, "height": 33, "depth": 45, "weight": 40, "quantity": 5},
        {"name": "Gizmo-B",  "width": 20, "height": 15, "depth": 15, "weight": 12, "quantity": 3}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())



<?php
$payload = [
  "items" => [
    [ "name" => "Widget-A", "width" => 10, "height" => 33, "depth" => 45, "weight" => 40, "quantity" => 5 ],
    [ "name" => "Gizmo-B",  "width" => 20, "height" => 15, "depth" => 15, "weight" => 12, "quantity" => 3 ]
  ]
];

$ch = curl_init("https://api.wyldapi.com/v1/binpacker/pack");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST  => "POST",
  CURLOPT_HTTPHEADER     => [
    "Authorization: Bearer <YOUR_TOKEN>",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS     => json_encode($payload),
  CURLOPT_RETURNTRANSFER => true
]);

$resp = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP $code\n$resp\n";



const payload = {
  items: [
    { name: "Widget-A", width: 10, height: 33, depth: 45, weight: 40, quantity: 5 },
    { name: "Gizmo-B",  width: 20, height: 15, depth: 15, weight: 12, quantity: 3 }
  ]
};

fetch("https://api.wyldapi.com/v1/binpacker/pack", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
})
  .then(res => res.json().then(data => ({ status: res.status, body: data })))
  .then(console.log)
  .catch(console.error);



import axios from "axios";

function patchPack() {
  axios.post(
    "https://api.wyldapi.com/v1/binpacker/pack",
    {
      items: [
        { name: "Widget-A", width: 10, height: 33, depth: 45, weight: 40, quantity: 5 },
        { name: "Gizmo-B",  width: 20, height: 15, depth: 15, weight: 12, quantity: 3 }
      ]
    },
    {
      headers: { Authorization: "Bearer <YOUR_TOKEN>" }
    }
  )
  .then(res => console.log(res.data))
  .catch(err => console.error(err.response?.data || err.message));
}

Home

Add a Box

Endpoint

Parameters

JSON Response

Response Fields

Code Snippets

Delete a Registered Box

Endpoint

Parameters

JSON Response

Response Fields

Code Snippets

Get All Boxes

Endpoint

Parameters

JSON Response

Response Fields

Code Snippets

Pack and Get Results

Endpoint

Parameters

JSON Response

Response Fields

Code Snippets