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.
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 |
|
carrier |
|
chargeable_weight |
|
cost |
|
created |
|
delivery_date |
|
exit_point |
|
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 |
|
insurance_fee |
|
is_ready |
|
oversize_fee |
|
processed |
|
processed_date |
|
processed_weight |
|
service |
|
shipment_id |
|
status |
|
surcharge |
|
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, "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" } }
GET /labels/9261299991753900000290
type=pdf
HTTP/1.1 200 OK
[blob]
POST /labels
{ "label": { "shipment_id": 1102 } }
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
{ "labels": [ "9261299991753900000301", "9261299991753900000323", "9261299991753900000339" ] }
HTTP/1.1 200 OK
[blob]
PUT /labels/9261299991753900000290/cancel
HTTP/1.1 200 OK