Automatic delivery status update - bug or misleading documentation

GraphQL Admin API Troubleshooting
1

Context :

  • We use Colissimo, Mondial Relay and Chronopost
  • France-based company
  • We do not purchase Shopify labels
  • Tracking numbers are added to our orders through the API

We recently noticed that the delivery status of our orders were never updated. We didn’t need to use them before, but now that we want to use the native self-service return feature, it is a blocking issue, as customers can not start a return if the delivery status of their order is not “delivered”. Currently, the status is stuck at “tracking number added”.

The GraphQL documentation states here (trackingInfo > company parameter) :

The name of the tracking company.

For tracking company names from the list below Shopify will automatically build tracking URLs for all provided tracking numbers, which will make the tracking numbers clickable in the interface.

Additionally, for the tracking companies listed on the Shipping Carriers help page Shopify will automatically update the fulfillment’s shipment_status field during the fulfillment process.

When checking the list of supported tracking companies on the Shipping Carriers help page, it appears that all our carriers are supported :

image
image803×1116 66.9 KB

However, when raising this issue with customer support, here was the answer :

image
image360×256 9.61 KB

If this is accurate, there are several problems :

  • Using external labels locks merchant out of native features (like the self-service return), unless they also implement their own system to update the delivery status, or another third-party app. I believe most merchants with enough parcels will have their own contracts with delivering companies, so won’t be able to use Shopify Labels anyway.
  • Using Shopify Labels makes using the fulfillment creation API for the concerned carriers completely useless. The description of the parameter in the API doc then has zero reason to exist if it just supports tracking number added through a Shopify label.
2

Hey again @Alex-OddBrew - thanks for the detailed write-up here.

Just confirming, the docs you’re referencing are correct on our end. The shipment_status field is designed to update automatically for fulfillments using any carrier on the Shipping Carriers help page, including Colissimo, Chronopost, and Mondial Relay, and this applies to API-created fulfillments with external tracking numbers too (not just Shopify Labels).

Before digging in further, a few common gotchas worth ruling out:

  1. The company string has to match the carrier name in the supported list exactly, including capitalization. "Colissimo" will match, but "colissimo" or "La Poste - Colissimo" might not. Same for "Chronopost" and "Mondial Relay" (note the space).

  2. If you’re sending trackingInfo.url alongside company and number, the URL can sometimes take priority over the company-based matching, so make sure it’s consistent with the carrier.

  3. For multiple tracking numbers on a single fulfillment, use numbers (plural) rather than mixing number and numbers, and make sure all numbers belong to the same carrier set via company.

If you’ve already tried all of the above and the status still isn’t updating, let me know and I can take a look internally on our end.

Hope to hear from you soon!

3

Hi again @Alan_G !

Thank you very much for your answer ! It is a shame that the Plus support provided me with such wrong information.
I looked up the values set by our logistician through GraphQL and I could see that Chronopost and Mondial Relay were indeed sent full uppercase, thus blocking the matching of the company (this absence of matching was actually visible when trying to edit the tracking info of the order in the admin, with the carrier field left blank).
For Colissimo I’m afraid it will be more complicated than that, the name of the company is set properly and the matching is visually okay, but the tracking still won’t update. My best guess here from what you told me is that maybe our logistician is sending the URL themselves and it’s overriding the automatic tracking, but if that’s the case they’re sending the exact same URL that Shopify is generating when I reset it through the API, so it would be weird if it was the culprit.

I updated the tracking info on a few orders to see how it behaves in the next days, I’ll get back to you if nothing works ! Thanks again.

4

Hey @Alex-OddBrew - glad the case sensitivity tip helped sort things out for Chronopost and Mondial Relay!

For Colissimo, your theory makes sense. If the URL is being passed alongside company and number, it can take priority over the company-based matching even when the URL itself looks correct. The cleanest test is to update those orders’ tracking info via the API with just company + number (no url) and see if shipment_status starts updating from there. If you’re already doing that and it’s still not budging after a few days with the next carrier scan, let me know and I’m happy to take a closer look on our end with a specific order in mind.

Hope to hear from you soon!

5

Hi Alan,

Thanks for the follow-up ! I modified 3 orders (one different carrier each) through the API, and none of the status were updated.

Additionally, I contacted the support again, and showed them this, and they maintained that only shipments sent through Shopify Labels will be updated, here is their answer :

Thank you for your follow-up and for sharing the community thread with us.

I understand your concern regarding the conflicting information about automated delivery status updates for supported carriers.

After reviewing the situation with our Developer Support team, I can clarify that while the API documentation indicates that shipment statuses can be automatically updated for supported carriers, in practice, this automatic progression of fulfillment status (such as “in transit” or “delivered”) is fully supported only when shipping labels are purchased directly through Shopify.

For labels created externally and added via the API, Shopify will correctly recognize the carrier and display clickable tracking links, but it may not automatically update the fulfillment status based on carrier scanning events.

Therefore, in your current setup, the delivery status progression is typically managed by your fulfillment system or the carrier, rather than Shopify’s native tracking updates.

To ensure the best experience:
Continue sending the exact carrier names as per Shopify’s supported formats.
Include valid tracking URLs when possible.
Rely on your fulfillment system or carrier updates for final delivery status confirmation.

I’m a bit lost, and I found some orders on our side that were automatically updated, but the number was manually entered by our staff, not through the API, and it was UPS or DHL shipments. Those were not purchased with Shopify Labels.

6

Hey @Alex-OddBrew - thanks for following up. I did a bit more digging and can confirm what Plus Support shared is partly correct. For the following carriers, tracking info will automatically update even if the merchant isn’t using Shopify Labels:

  • AxleHire

  • Better Trucks

  • CDL Last Mile

  • Canada Post

  • DHL Express

  • DHL Express DE

  • DHL eCommerce

  • FedEx

  • GLS

  • GLS US

  • Lasership

  • Lone Star Overnight

  • OnTrac

  • TForce Final Mile

  • UPS

  • USPS

  • United Delivery Service

However, these tracking services only update when the merchant uses Shopify Labels:

  • BRT

  • Canada Post

  • Chronopost

  • Colissimo

  • Correos

  • Correos Express

  • DHL Express

  • DHL eCommerce

  • DPD UK

  • Deutsche Post DHL

  • Deutsche Post Mail

  • DoorDash

  • Evri

  • FedEx

  • Mondial Relay

  • Poste Italiane

  • Purolator

  • Royal Mail

  • SEUR

  • Sendle

  • UPS

  • UPS Canada

  • USPS

  • Yodel

Our documentation isn’t super clear on that for sure, so I’ll push for that to be updated on our end. I can’t say for sure why some are supported or aren’t at the moment, but if it’s helpful I can pass along your feedback and see if it’s possible to share more info on that?

I also noticed with have USPS/UPS listed in both cases, so I’ll do some digging into that on my side here as well.

8

Following up on the above - the repeated entries (Canada Post, DHL Express, DHL eCommerce, FedEx, UPS, USPS) work with both methods - just wanted to clarify.

I’m going to go ahead and look into improving our docs internally here to reflect this - hope to hear from you soon and hope this helps :slight_smile:

9

Hi @Alan_G,

Thank you for your answer and clearing that up ! This explains why our packages sent with DHL received the status updates.

An update on the documentation would be much appreciated indeed, as none of this behavior is explicit currently.

Thanks again !

10

Hey @Alex-OddBrew - thanks for confirming and no worries, glad that helped clear things up.

I agree the current docs don’t make this distinction clear enough, especially the difference between generating clickable tracking links and automatically progressing shipment status. I’ve started working on a docs clarification on my end, so we can hopefully make that behaviour more explicit.

Let me know if anything else comes up on this one.