Labels

The Labels resource allows a user to create, cancel, retrieve, and track labels for verified shipments. Labels can only be created for shipments that have a verified shipping address or were manually overridden. A label cannot be created if there is already an uncancelled or processed label for the shipment. Labels that have been processed cannot be cancelled. The user is responsible for paying the shipping costs if a label is cancelled but still processed at a facility. Test labels are routinely purged from the system.

Applications should utilize the PUT /labels/{id} action if they want to assign shipments to overpacks while scanning their labels.

Users that need smaller labels than the default 4x6 inch should set the size property to "4x4" when creating a label. There are a few caveats: comments and logos will not be displayed due to space limitations, and it does not apply for all routes.

Note: Both the label's tracking_number and id can replace the {id} in all actions.

Actions

GET /labels/{id} Retrieves a label
POST /labels Creates a label
POST /labels/bulk Create a PDF with up to 100 labels
PUT /labels/{id} Updates a label
PUT /labels/{id}/cancel Cancels a label

Properties

cancelled

{"cancelled": false}

Boolean - Whether or not the label was cancelled. Set by the system.
cost

{"cost": 3.15}

Decimal - The shipping cost for the label. Set by the system.
created

{"created": "2015-05-01 20:19:18"}

String - The date and time the label was created. Set by the system.
delivery_date

{"delivery_date": "2015-05-10"}

Date - The date the shipment was delivered. Default is NULL. Set by the system.
events 
{
    "events": [
        {
            "time": "2015-09-15 12:46:04",
            "city": "New York City",
            "province": "NY",
            "postal_code": "10001",
            "code": 200,
            "description": "DELIVERED"
        }
    ]
}

Array - The tracking history for this label in descending order. Set by the system. Refer to the Tracking Events page for a list.

time: String - The local date and time the event occurred.
city: String - The city the event took place in.
province: String - The province the event took place in.
postal_code: String - The postal code the event took place in.
code: Integer - A code matching the description and to help identify the event.
description: String - A description of the event.
id

{"id": 2382131}

Integer - The unique ID of the label in the system. Set by the system.
overpack_id

{"overpack_id": 100001}

Integer - The ID of the overpack you want to assign this label's shipment to, or NULL if you want to remove the shipment from the overpack. The shipment's entry_point must match the overpack. Only required for updating a shipment's overpack_id while scanning labels.
override_fee

{"override_fee": 0.25}

Decimal - The cost for overriding address verification. Default is 0. Set by the system.
oversize_fee

{"oversize_fee": 0.00}

Decimal - Additional cost for an oversized shipment. Default is 0. Set by the system.
processed

{"processed": false}

Boolean - Whether or not the label was processed at our facility. Set by the system.
processed_date

{"processed_date": "2015-05-03"}

Date - The date the label was first processed at a facility. Default is NULL. Set by the system.
processed_weight

{"processed_weight": 0.284}

Decimal - The processed weight of the shipment at a facility. Default is NULL. Set by the system.
service

{"service": "BoxC Parcel"}

String - The type of shipping service this label is billed for. Set by the system.
shipment_id

{"shipment_id": 1014}

Integer - The ID of the shipment you want to create a label for, or is associated with the label.
size

{"size": "4x4"}

String - This property is used to determine the size of the label in inches you wish to create. Anything smaller than 4x6 will not display a logo or comments. The different size options are:
  • 4x6 (default)
  • 4x4
status

{"status": "Customs"}

String - The latest status of the shipment. Set by the system. Can be one of:
  • Pending
  • Processed
  • Canceled
  • Customs
  • En Route
  • Exception
  • Delivered
tax

{"tax": 4.20}

Decimal - The tax owed for this shipment. Set by the system.
tracking_number

{"tracking_number": "9261299991753900000290"}

String - The tracking number for the label. Set by the system.
GET
/labels/{id}
Retrieves a label
type The data stream type if you don't want the label details and need the actual BLOB. Only PDF is accepted.
request
GET /labels/9261299991753900000290
response

HTTP/1.1 200 OK

{
    "label": {
        "cancelled": true,
        "cost": 3.25,
        "created": "2015-05-17 04:20:00",
        "delivery_date": "2015-09-15",
        "events": [
            {
                "time": "2015-09-15 12:46:04",
                "city": "New York City",
                "province": "NY",
                "postal_code": "10001",
                "code": 200,
                "description": "DELIVERED"
            },
            {
                "...": "..."
            }
        ],
        "id": 11102912,
        "override_fee": 0,
        "oversize_fee": 0,
        "processed": false,
        "processed_date": null,
        "processed_weight": null,
        "service": "BoxC Parcel",
        "shipment_id": 1014,
        "status": "Pending",
        "tax": 0,
        "tracking_number": "9261299991753900000290"
    }
}
request
GET /labels/9261299991753900000290 
type=pdf
response

HTTP/1.1 200 OK

[blob]
POST
/labels
Creates a label
request
POST /labels 
{
    "label": {
        "shipment_id": 1102,
        "size": "4x6"
    }
}
response

HTTP/1.1 201 Created

{
    "label": {
        "cancelled": false,
        "cost": 3.25,
        "delivery_date": null,
        "events": [],
        "id": 721230,
        "override_fee": 0,
        "oversize_fee": 0,
        "processed": false,
        "processed_date": null,
        "processed_weight": null,
        "service": "BoxC Parcel",
        "shipment_id": 1102,
        "status": "Pending",
        "tax": 0,
        "tracking_number": "9261299991753900000301"
    }
}
POST
/labels/bulk
Create a PDF with up to 100 labels
request
POST /labels/bulk 
{
    "labels": [
        "9261299991753900000301",
        "9261299991753900000323",
        "9261299991753900000339"
    ]
}
response

HTTP/1.1 200 OK

[blob]
PUT
/labels/{id}
Updates a label
request
PUT /labels/9261299991753900000301 
{
    "label": {
        "overpack_id": 100001
    }
}
response

HTTP/1.1 200 OK


		

		

		

			
request

			PUT /labels/9261299991753900000301
						
{
    "label": {
        "overpack_id": null
    }
}

		

		

		

			
response

			
HTTP/1.1 200 OK

			

		

	






	

		
PUT

		
/labels/{id}/cancel

	

	

		Cancels a label
	

	

		

			
request

			PUT /labels/9261299991753900000290/cancel
		

		

		

			
response

			
HTTP/1.1 200 OK