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.
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 |
|
cost |
|
created |
|
delivery_date |
|
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 |
|
overpack_id |
|
override_fee |
|
oversize_fee |
|
processed |
|
processed_date |
|
processed_weight |
|
service |
|
shipment_id |
|
size |
|
status |
|
tracking_number |
|
type |
The data stream type if you don't want the label details and need the actual BLOB. Only PDF is accepted. |
GET /labels/9261299991753900000290
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", "tracking_number": "9261299991753900000290" } }
GET /labels/9261299991753900000290
type=pdf
HTTP/1.1 200 OK
[blob]
POST /labels
{ "label": { "shipment_id": 1102, "size": "4x6" } }
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", "tracking_number": "9261299991753900000301" } }
POST /labels/bulk
{ "labels": [ "9261299991753900000301", "9261299991753900000323", "9261299991753900000339" ] }
HTTP/1.1 200 OK
[blob]
PUT /labels/9261299991753900000301
{ "label": { "overpack_id": 100001 } }
HTTP/1.1 200 OK
PUT /labels/9261299991753900000301
{ "label": { "overpack_id": null } }
HTTP/1.1 200 OK
PUT /labels/9261299991753900000290/cancel
HTTP/1.1 200 OK