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:
We create a return via return_create at the time the admin approves it
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?
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 instead. One concept helps here: in ShipHero, the tracking number belongs to the return’s label, and labels come in two kinds:
Labels purchased from a real carrier (UPS, FedEx, etc.) get their tracking number issued by the carrier itself, so they are intentionally not editable.
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.