Add new tracking number to existing shipment using REST API in Magento 2

Add new tracking number to existing shipment using REST API in Magento 2

August 11, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Add new tracking number to existing shipment using REST API in Magento 2

Adding Additional Tracking Numbers to Existing Shipments in Magento 2: A Step-by-Step Guide

As an e-commerce developer, you may find yourself needing to add supplementary tracking numbers to already created shipments in your Magento 2 store. This process involves understanding the correct API endpoint and constructing the appropriate payload for the HTTP request.

Why You Can’t Add Tracking Numbers Using the Same Endpoint

The initial confusion arises because both endpoints allow you to create new shipments, but they don’t support adding additional tracking numbers to existing ones. The POST /V1/orders/{orderId}/shipments endpoint expects a complete shipment object with products and tracking information.

When you try to add just the tracking number using this endpoint, Magento interprets it as an incomplete shipment without any products, hence the error message “you can’t create a shipment without products”.

The Correct Endpoint for Adding Tracking Numbers

To add new tracking numbers to existing shipments, you should use the POST /V1/shipments/{id}/tracks endpoint. This endpoint allows you to associate an additional track with an already created shipment.

Here’s how you can construct your request:

fetch('http://your_magento_store.com/rest/V1/shipments/2/tracks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <ACCESS_TOKEN>'
  },
  body: JSON.stringify({
    "track_id": "034625787769",
    "title": "FedEx",
    "carrier_code": "fedex",
    "number": "123456789"
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Replace <ACCESS_TOKEN> with the access token for your Magento admin account. The request body is a JSON object containing the track information you want to add.

The Importance of Documentation and Learning Resources

As a beginner in Magento, it’s easy to get overwhelmed by the extensive documentation. However, understanding how to navigate and interpret these resources effectively will save you significant time in the long run.

I recommend bookmarking the official Magento 2 REST API documentation for quick reference. For more complex tasks or when you feel stuck, don’t hesitate to consult trusted third-party resources like the blog posts on Laravel Company’s Magento 2 section.

Conclusion

Adding tracking numbers to existing shipments in Magento 2 requires a different approach than creating new shipments. By understanding and utilizing the POST /V1/shipments/{id}/tracks endpoint, you can efficiently add supplementary track information without encountering the “no products” error.

Remember, the key lies in constructing the correct request format and using the appropriate API resource based on the action you’re performing. With practice and familiarity with the Magento 2 documentation, your development process will become smoother and more efficient over time.

Magento 2 Catalog API Orders

Our network