Skip to content

Commit bba0a39

Browse files
semarjsemarj
authored
Merge pull request #34 from micaelaw/list-labels-by-tracking-number
List labels by tracking number
2 parents e20f0ab + 872d965 commit bba0a39

File tree

3 files changed

+220
-0
lines changed

3 files changed

+220
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ the all tracking events for a given shipment.
6262
- [track_package_by_carrier_code_and_tracking_number](./docs/track_package_by_carrier_code_and_tracking_number_example.md) - Track a package by `carrier_code` and `tracking_number`. This method returns
6363
the all tracking events for a given shipment.
6464
- [void_label_by_label_id](./docs/void_label_by_label_id_example.md) - Void a shipping label you created using ShipEngine by its `label_id`. This method returns an object that indicates the status of the void label request.
65+
- [list_labels_by_tracking_number] (./docs/list_labels_by_tracking_number.md) - List the labels associated with the inputted tracking number.
6566

6667
Class Objects
6768
-------------

‎docs/list_labels_by_tracking_number.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
List Labels By Tracking Number Documentation
2+
====================================
3+
[ShipEngine](www.shipengine.com) allows you to get a list of labels using a tracking number.
4+
5+
Please see [our docs](https://www.shipengine.com/docs/reference/list-labels/) to learn more about listing labels.
6+
7+
8+
Input Parameters
9+
----------------
10+
The `list_labels_by_tracking_number` method accepts a string that contains the tracking number of the desired label(s).
11+
12+
13+
Output
14+
------
15+
The `list_labels_by_tracking_number` method returns a dictionary of the response from ShipEngine, including a list of labels with the inputted tracking number.
16+
17+
18+
Example
19+
=======
20+
```python
21+
import os
22+
23+
from shipengine import ShipEngine
24+
from shipengine.errors import ShipEngineError
25+
26+
27+
def list_labels_by_tracking_number_demo():
28+
api_key = os.getenv("SHIPENGINE_API_KEY")
29+
30+
shipengine = ShipEngine(
31+
{"api_key": api_key, "page_size": 75, "retries": 3, "timeout": 10}
32+
)
33+
try:
34+
result = shipengine.list_labels_by_tracking_number(tracking_number="1ZXXXXXXXXXXXXXXXX")
35+
print("::SUCCESS::")
36+
print(result)
37+
except ShipEngineError as err:
38+
print("::ERROR::")
39+
print(err.to_json())
40+
41+
42+
list_labels_by_tracking_number_demo()
43+
```
44+
45+
Example Output
46+
==============
47+
```python
48+
{
49+
"labels": [
50+
{
51+
"label_id": "se-92516364",
52+
"status": "completed",
53+
"shipment_id": "se-194998284",
54+
"external_shipment_id": "SEAuto-gYd5iXdyT0uvgfyLWAcfrA",
55+
"external_order_id": None,
56+
"ship_date": "2025-12-11T08:00:00Z",
57+
"created_at": "2025-12-11T21:06:39.307Z",
58+
"shipment_cost": {"currency": "usd", "amount": 95.41},
59+
"insurance_cost": {"currency": "usd", "amount": 0.0},
60+
"requested_comparison_amount": None,
61+
"rate_details": [
62+
{
63+
"rate_detail_type": "shipping",
64+
"carrier_description": "TransportationCharge",
65+
"carrier_billing_code": None,
66+
"carrier_memo": None,
67+
"amount": {"currency": "usd", "amount": 95.410},
68+
"billing_source": "carrier",
69+
}
70+
],
71+
"tracking_number": "1ZXXXXXXXXXXXXXXXX",
72+
"is_return_label": False,
73+
"rma_number": None,
74+
"is_international": False,
75+
"batch_id": "",
76+
"carrier_id": "se-2815273",
77+
"service_code": "ups_ground",
78+
"package_code": "package",
79+
"voided": False,
80+
"voided_at": None,
81+
"label_format": "zpl",
82+
"display_scheme": "label",
83+
"label_layout": "4x6",
84+
"trackable": True,
85+
"label_image_id": None,
86+
"carrier_code": "ups",
87+
"carrier_weight": None,
88+
"confirmation": "none",
89+
"tracking_status": "in_transit",
90+
"label_download": {
91+
"href": "https://api.shipengine.com/v1/downloads/14/F9uiUwnwnEu0602g0lc_rw/label-92516364.zpl"
92+
},
93+
"form_download": None,
94+
"qr_code_download": None,
95+
"insurance_claim": None,
96+
"paperless_download": None,
97+
"packages": [
98+
{
99+
"package_id": 72599271,
100+
"package_code": "package",
101+
"weight": {"value": 20.00, "unit": "pound"},
102+
"dimensions": {
103+
"unit": "inch",
104+
"length": 24.00,
105+
"width": 12.00,
106+
"height": 6.00,
107+
},
108+
"insured_value": {"currency": "usd", "amount": 0.00},
109+
"tracking_number": "1ZXXXXXXXXXXXXXXXX",
110+
"label_download": {
111+
"href": "https://api.shipengine.com/v1/downloads/14/_g6zkt9fs0us7Rrktmdpzw/labelpackage-72599271.zpl"
112+
},
113+
"qr_code_download": None,
114+
"paperless_download": None,
115+
"label_messages": {
116+
"reference1": None,
117+
"reference2": None,
118+
"reference3": None,
119+
},
120+
"external_package_id": None,
121+
"content_description": None,
122+
"sequence": 1,
123+
"alternative_identifiers": [],
124+
"has_label_documents": False,
125+
"has_form_documents": False,
126+
"has_qr_code_documents": False,
127+
"has_paperless_label_documents": False,
128+
},
129+
{
130+
"package_id": 72599272,
131+
"package_code": "package",
132+
"weight": {"value": 10.00, "unit": "pound"},
133+
"dimensions": {
134+
"unit": "inch",
135+
"length": 10.00,
136+
"width": 10.00,
137+
"height": 10.00,
138+
},
139+
"insured_value": {"currency": "usd", "amount": 0.00},
140+
"tracking_number": "1ZXXXXXXXXXXXXXXXX",
141+
"label_download": {
142+
"href": "https://api.shipengine.com/v1/downloads/14/UTu1HZzgMkKSV-HXM16PPQ/labelpackage-72599272.zpl"
143+
},
144+
"qr_code_download": None,
145+
"paperless_download": None,
146+
"label_messages": {
147+
"reference1": None,
148+
"reference2": None,
149+
"reference3": None,
150+
},
151+
"external_package_id": None,
152+
"content_description": None,
153+
"sequence": 2,
154+
"alternative_identifiers": [],
155+
"has_label_documents": False,
156+
"has_form_documents": False,
157+
"has_qr_code_documents": False,
158+
"has_paperless_label_documents": False,
159+
},
160+
],
161+
"charge_event": "carrier_default",
162+
"alternative_identifiers": [],
163+
"shipping_rule_id": None,
164+
"tracking_url": f"http://wwwapps.ups.com/WebTracking/processRequest?HTMLVersion=5.0&Requester=NES&AgreeToTermsAndConditions=yes&loc=en_US&tracknum=1ZXXXXXXXXXXXXXXXX",
165+
"ship_to": {
166+
"geolocation": [],
167+
"instructions": None,
168+
"name": "Jane Doe",
169+
"phone": None,
170+
"email": None,
171+
"company_name": None,
172+
"address_line1": "525 S Winchester Blvd",
173+
"address_line2": None,
174+
"address_line3": None,
175+
"city_locality": "San Jose",
176+
"state_province": "CA",
177+
"postal_code": "95128",
178+
"country_code": "US",
179+
"address_residential_indicator": "yes",
180+
},
181+
}
182+
],
183+
"total": 1,
184+
"page": 1,
185+
"pages": 1,
186+
"links": {
187+
"first": {
188+
"href": f"https://api.shipengine.com/v1/labels?tracking_number=1ZXXXXXXXXXXXXXXXX&page=1&page_size=25"
189+
},
190+
"last": {
191+
"href": f"https://api.shipengine.com/v1/labels?tracking_number=1ZXXXXXXXXXXXXXXXX&page=1&page_size=25"
192+
},
193+
"prev": {},
194+
"next": {},
195+
},
196+
}
197+
```
198+
199+
Exceptions
200+
==========
201+
202+
- This method will only throw an exception that is an instance/extension of
203+
([ShipEngineError](../shipengine/errors/__init__.py)) if there is a problem if a problem occurs, such as a network
204+
error or an error response from the API.

‎shipengine/shipengine.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,3 +158,18 @@ def void_label_by_label_id(
158158
"""
159159
config = self.config.merge(new_config=config)
160160
return self.client.put(endpoint=f"v1/labels/{label_id}/void", config=config)
161+
162+
def list_labels_by_tracking_number(
163+
self, tracking_number: str, config: Union[str, Dict[str, Any]] = None
164+
) -> Dict[str, Any]:
165+
"""
166+
Lists labels with the specified tracking_number
167+
168+
:param str tracking_number: The tracking_number of the label(s) you wish to get.
169+
:returns Dict[str, Any]: The response from ShipEngine API including the label(s) with the specified
170+
tracking_number.
171+
"""
172+
config = self.config.merge(new_config=config)
173+
return self.client.get(
174+
endpoint=f"v1/labels?tracking_number={tracking_number}", config=config
175+
)

0 commit comments

Comments
 (0)