Labels

The Labels resource allows a user to create, cancel, retrieve, and track labels for shipments. A label can't be created if there is already an uncancelled or processed label for the shipment. Labels that have been processed can't 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.

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}/cancel Cancels a label

Properties

cancelled

{"cancelled": false}

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

{"carrier": "USPS"}

String - The final mile carrier for this label. Set by the system.
chargeable_weight

{"chargeable_weight": 0.3}

Decimal - The chargeable weight for this shipment which is the greater of gross weight and volumetric weight. 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.
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 determined irrelevant for the destination.
events 
{
    "events": [
        {
            "carrier": "USPS",
            "time": "2015-09-15 12:46:04",
            "city": "New York City",
            "province": "NY",
            "postal_code": "10001",
            "country": "US",
            "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.

carrier: String - The carrier that provided this event.
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.
country: String - The country 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.
insurance_fee

{"insurance_fee": 0}

Decimal - The cost of insurance for this shipment if requested. Default is 0. Set by the system.
is_ready

{"is_ready": true}

Boolean - Indicates the label file is ready for download. This is true for most cases during shipment creation. Some carriers provide labels asynchronously. 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.
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
surcharge

{"surcharge": 0.75}

Decimal - Additional cost for this shipment based on the route and chargeable weight. Default is 0. 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,
        "carrier": "USPS",
        "cost": 3.25,
        "created": "2015-05-17 04:20:00",
        "delivery_date": "2015-09-15",
        "exit_point": "JFK",
        "events": [
            {
                "carrier": "USPS",
                "time": "2015-09-15 12:46:04",
                "city": "New York City",
                "province": "NY",
                "postal_code": "10001",
                "country": "US",
                "code": 200,
                "description": "DELIVERED"
            },
            {
                "...": "..."
            }
        ],
        "id": 11102912,
        "insurance_fee": 0,
        "is_ready": true,
        "oversize_fee": 0,
        "processed": false,
        "processed_date": null,
        "processed_weight": null,
        "service": "BoxC Parcel",
        "shipment_id": 1014,
        "status": "Pending",
        "surcharge": 0.75,
        "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
    }
}
response

HTTP/1.1 201 Created

{
    "label": {
        "cancelled": false,
        "carrier": "USPS",
        "cost": 3.25,
        "delivery_date": null,
        "events": [],
        "exit_point": "JFK",
        "id": 721230,
        "insurance_fee": 0,
        "is_ready": true,
        "oversize_fee": 0,
        "processed": false,
        "processed_date": null,
        "processed_weight": null,
        "service": "BoxC Parcel",
        "shipment_id": 1102,
        "status": "Pending",
        "surcharge": 0.75,
        "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}/cancel
Cancels a label
request
PUT /labels/9261299991753900000290/cancel
response

HTTP/1.1 200 OK