Overpacks

The Overpacks resource allows a user to combine many Shipments into one object for faster clearance with BoxC and Customs. An overpack can be a carton, container, pallet, or bag. Regardless, it must contain an overpack label on the outside. Empty overpacks are routinely purged from the system.

When creating an overpack it's recommended to provide one or more shipment ID, label ID, or tracking numbers in the request. The overpack will inherit the first shipment's (n) attributes like the entry_point, service, terms, etc. All shipments require identical attributes to be a part of the same overpack. Errors will be returned if the n + 1 shipments do not match the first one. An error message will be present in the shipments array for each shipment that fails while creating or updating overpacks. Shipments that pass validation will still be added in the same request.

The system will calculate the routing and other applicable carrier logic to determine the physical appearance of the label. Some carriers require custom messaging on the labels while others require a completely different label altogether. The system handles this logic on your behalf.

Note: Shipments without labels and cancelled shipments can't be added to overpacks.

The overpack(s) must be dropped off at the BoxC collection center indicated by the entry_point. Some entry points do not require overpacking and the system will prevent you from creating one. Deleting an overpack unassigns all shipments from it.

Note: A client won't be able to print an overpack label until at least one shipment is assigned to it.

Actions

GET /overpacks Retrieves a paginated list of overpacks
GET /overpacks/{id} Retrieves an overpack
POST /overpacks Creates an overpack
PUT /overpacks/{id} Updates an overpack
DELETE /overpacks/{id} Deletes an overpack

Properties

carrier

{"carrier": "USPS"}

String - The final mile carrier for this overpack inherited from the shipments. Set by the system.
contains_dg

{"contains_dg": true}

Boolean - Indicates the overpack contains a shipment with a dangerous good. Set by the system.
created

{"created": "2015-05-05 15:43:03"}

String - The date and time the overpack was created. Set by the system.
entry_point

{"entry_point": "LAXI01"}

String - The drop off location for this overpack. See Entry Points for a list of codes. All shipments must have the same entry point. The system determines the entry point based on the shipments.
exit_point

{"exit_point": "LAX"}

String - The exit port for this shipment determined by the system. This value is null for shipments where exit port is deemed inconsequential for the destination. Default is null.
external_tracking

{"external_tracking": null}

String - Some carriers require their own tracking numbers to be present on the overpack label. Set by the system. Default is null.
height

{"height": 50}

Integer - The height of the overpack in cm. Required to manifest.
id

{"id": 12019}

Integer - The ID of the overpack. Set by the system.
length

{"length": 91}

Integer - The length of the overpack in cm. Required to manifest.
locked

{"locked": false}

Boolean - Whether or not the overpack is locked. Overpacks are locked by the system when they are part of a manifest. They can't be modified once manifested. Set by the sytem.
manifest_id

{"manifest_id": 1010023}

Integer - The ID of the manifest this overpack is linked to. Set by the system.
service

{"service": "BoxC Parcel"}

String - The BoxC service type. All shipments inside this overpack must have the same service. The system determines the service type based on the shipments.
shipments 

{
    "shipments": [
        {
            "id": 1212,
            "label_id": 781028,
            "tracking_number": "9274899999999900001785"
        },
        {
            "id": 1213,
            "label_id": 781029,
            "tracking_number": "9274899999999900001793"
        },
        {
            "id": 1214,
            "label_id": null,
            "tracking_number": null
        }
    ]
}

Array - A list of shipments inside this overpack. Clients should use this to add multiple shipments at once. Only one child attribute it required to add the shipment to the overpack. The system will check for matching shipments in the following order: shipments[].id, shipments[].label_id, or shipments[].tracking_number. Only present when getting or setting a single overpack. At least one labelled shipment is needed to determine the routing logic of the overpack.

  • id Integer - The shipment ID.
  • label_id Integer - The label ID.
  • tracking_number String - The shipment's tracking number.
  • error String - Error message only present when a shipment can't be assigned to an overpack because of a mismatch of attributes.
terms

{"terms": "DDU"}

String - The shipping terms for this overpack inherited from the shipments. All shipments in the overpack must have the same terms. Set by the system. Default is null.
total_shipments

{"total_shipments": 432}

Integer - The total number of shipments in the overpack. Set by the system. Only present when getting a list of overpacks.
type86

{"type86": false}

Boolean - Indicates the overpack contains only Type 86 shipments. This will be false for most clients. Set by the system.
weight

{"weight": 87.5}

Decimal - The weight of the overpack in KG rounded to 1 significant digit after the decimal point. Required to manifest.
width

{"width": 30}

Integer - The width of the overpack in cm. Required to manifest.
GET
/overpacks/{id}
Retrieves an overpack
type The data stream type if you don't want the overpack details. Only pdf is permitted. A label won't be returned unless the overpack contains shipments.
request
GET /overpacks/11232
response

HTTP/1.1 200 OK

{
    "overpack": {
        "carrier": "DHLeC",
        "contains_dg": true,
        "created": "2020-02-16 18:22:55",
        "entry_point": "CVG001",
        "exit_point": "CVG",
        "external_tracking": null,
        "height": 10,
        "id": 1002685,
        "length": 10,
        "locked": false,
        "manifest_id": null,
        "service": "BoxC Parcel",
        "shipments": [
            {
                "id": "171083",
                "label_id": "845",
                "tracking_number": "9274890240788200000653"
            },
            {
                "id": "171086",
                "label_id": "850",
                "tracking_number": "9274890240788200000707"
            }
        ],
        "terms": "DDU",
        "type86": true,
        "weight": 1.0,
        "width": 10
    }
}
request
GET /overpacks/11232 
type=pdf
response

HTTP/1.1 200 OK

[blob]
POST
/overpacks
Creates an overpack
request
POST /overpacks 
{
    "overpack": {
        "weight": 8.0,
        "length": 20,
        "width": 20,
        "height": 20,
        "shipments": [
            {
                "tracking_number": "9274890240788200000653"
            },
            {
                "tracking_number": "9274890240788200000707"
            }
        ]
    }
}
response

HTTP/1.1 400 Bad Request

{
    "overpack": {
        "contains_dg": false,
        "created": null,
        "entry_point": "CVG001",
        "exit_point": null,
        "external_tracking": null,
        "height": 20,
        "id": null,
        "length": 20,
        "locked": false,
        "manifest_id": null,
        "service": null,
        "shipments": [
            {
                "tracking_number": "9274890240788200000653",
                "id": 171083,
                "label_id": 845,
                "error": "Shipments to 'CVG001' don't require an overpack"
            },
            {
                "tracking_number": "9274890240788200000707",
                "id": 171086,
                "label_id": 850,
                "error": "Shipments must have the same entry point"
            }
        ],
        "terms": null,
        "type86": false,
        "weight": 8.0,
        "width": 20
    }
}
request
POST /overpacks 
{
    "overpack": {
        "weight": 8.0,
        "length": 20,
        "width": 20,
        "height": 20,
        "shipments": [
            {
                "tracking_number": "2KNG118400631803007035400000"
            }
        ]
    }
}
response

HTTP/1.1 201 Created

{
    "overpack": {
        "contains_dg": false,
        "created": "2020-08-26 17:09:35",
        "entry_point": "LAXI01",
        "exit_point": "YYZ",
        "external_tracking": null,
        "height": 20,
        "id": 1002703,
        "length": 20,
        "locked": false,
        "manifest_id": null,
        "service": "BoxC Parcel",
        "shipments": [
            {
                "tracking_number": "2KNG118400631803007035400000",
                "id": 1000017,
                "label_id": 875
            }
        ],
        "terms": "DDP",
        "type86": false,
        "weight": 8.0,
        "width": 20
    }
}
PUT
/overpacks/{id}
Updates an overpack
request
PUT /overpacks/1002685 
{
    "overpack": {
        "weight": 10.0,
        "length": 25,
        "width": 25,
        "height": 25,
        "shipments": [
            {
                "tracking_number": "9274890240788200000653"
            }
        ]
    }
}
response

HTTP/1.1 200 OK

{
    "overpack": {
        "carrier": null,
        "created": "2020-02-16 18:22:55",
        "contains_dg": true,
        "entry_point": "SZXI01",
        "exit_point": "LAX",
        "external_tracking": null,
        "height": 25,
        "id": 1002685,
        "length": 25,
        "locked": false,
        "manifest_id": null,
        "service": "BoxC Parcel",
        "shipments": [
            {
                "id": "171083",
                "label_id": "845",
                "tracking_number": "9274890240788200000653"
            },
            {
                "id": "171086",
                "label_id": "850",
                "tracking_number": "9274890240788200000707"
            }
        ],
        "terms": "DDU",
        "type86": false,
        "weight": 10.0,
        "width": 25
    }
}
DELETE
/overpacks/{id}
Deletes an overpack
request
DELETE /overpacks/11233
response

HTTP/1.1 200 OK