# Adding Tracking Number to Existing Return

**URL:** <https://community.shiphero.com/t/adding-tracking-number-to-existing-return/3764>\
**Category:** GraphQL API\
**Created:** [August 20, 2026, 12:05pm UTC](https://community.shiphero.com/t/adding-tracking-number-to-existing-return/3764 "2026-08-20T12:05:04Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![airalingat](https://avatars.discourse-cdn.com/v4/letter/a/73ab20/32.png) [@airalingat](https://community.shiphero.com/u/airalingat)\
**Post date:** [August 20, 2026, 12:05pm UTC](https://community.shiphero.com/t/adding-tracking-number-to-existing-return/3764/1 "2026-08-20T12:05:04Z")

</div>

Hi ShipHero Support,

We’re integrating ShipHero’s Returns API into our returns portal and have a question about adding a customer-submitted tracking number to an existing return.

Our flow is:

1. We create a return via `return_create` at the time the admin approves it
2. The customer then ships their items and submits their tracking number through our portal separately

We need to update the return in ShipHero with that tracking number after creation. Looking at the documentation, we couldn’t find a mutation that supports this — `return_update_status` only appears to change the status field.

**Our question:** Is there a mutation (documented or otherwise) that allows us to add or update a `tracking_number` on an existing return after it’s been created? For example, does `return_update_status` accept a `tracking_number` field even if it’s not in the docs?

Any guidance would be greatly appreciated.

Thanks,  
Aira Lingat

---

<div class="post-metadata">

**Author:** ![lpezza](https://avatars.discourse-cdn.com/v4/letter/l/439d5e/32.png) [@lpezza](https://community.shiphero.com/u/lpezza)\
**Post date:** [August 21, 2026, 8:49pm UTC](https://community.shiphero.com/t/adding-tracking-number-to-existing-return/3764/2 "2026-08-21T20:49:41Z")

</div>

Hi Aira, i hope you are doing well!

Thanks for the detailed question, and for checking the docs first.

Unfortunately there is currently no mutation in the Public API that allows adding or updating a tracking number on a return after it has been created. This can be done through the [ShipHero web app](https://app.shiphero.com/dashboard/returns) instead. One concept helps here: in ShipHero, the tracking number belongs to the return’s **label** , and labels come in two kinds:

1. **Labels purchased from a real carrier** (UPS, FedEx, etc.) get their tracking number issued by the carrier itself, so they are intentionally not editable.
2. **Generic labels** are the opposite: they have no carrier behind them, their tracking number is meant to be entered manually, and that is the kind your flow needs, since your customer ships on their own and reports the number afterwards.

Depending on how you are calling `return_create`, your returns today are in one of two states, and the web app handles both:

- **If you are not sending `create_label` or `tracking_number`:** the return is created with no label at all. On the return’s detail page, the _Re-Generate Label_ button creates a generic one.
- **If you are sending `create_label: true` with a generic carrier:** the return already has a label, with the tracking number empty.
- **If you are sending `create_label: true` with a real carrier (UPS, FedEx, etc.):** ShipHero purchases the label from that carrier, and the tracking number is issued by the carrier at that moment. In this case the number already exists and cannot be edited, from the API or from the web app.

In either case, once a generic label exists, the tracking number appears on the return’s detail page as a clickable link (it shows “Add a tracking number” when empty). Clicking it opens a form where the number can be entered or changed at any time.

Best regards, Luciano.