UPS REST API - Tracking vs Track by Reference

As long as I have the tracking number, the UPS Track API works great. I use it as described on the help page:

const inquiryNumber = "my tracking number";
$query = array(
  "locale" => "en_US",
  "returnSignature" => "false",
  "returnMilestones" => "false",
  "returnPOD" => "false"
);

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <YOUR_TOKEN_HERE>",
    "transId: string",
    "transactionSrc: testing"
  ],
  CURLOPT_URL => "https://wwwcie.ups.com/api/track/v1/details/" . inquiryNumber . "?" . http_build_query($query),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$error = curl_error($curl);

curl_close($curl);

if ($error) {
  echo "cURL Error #:" . $error;
} else {
  echo $response;
}

And get back a complete response, which includes the reference number, which is the original order id:

[referenceNumber] => Array
    (
        [0] => Array
            (
                [type] => SHIPMENT
                [number] => 657780
                [code] => 01
                [description] => Shipper Assigned General
            )

        [1] => Array
            (
                [type] => PACKAGE
                [number] => 657780
                [code] => 01
                [description] => Shipper Assigned General
            )

    )

The issue is, I need to handle the situation where I don't have the tracking number, I just have the reference number (the order id). UPS says they have an API for that, the Track by Reference Number API. When I use their code as shown in the example:

const referenceNumber = "order number";
$query = array(
  "locale" => "en_US",
  "fromPickUpDate" => "currentDate-14",
  "toPickUpDate" => "currentDate",
  "refNumType" => "SmallPackage. Valid values: SmallPackage, fgv"
);

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <YOUR_TOKEN_HERE>",
    "transId: string",
    "transactionSrc: testing"
  ],
  CURLOPT_URL => "https://wwwcie.ups.com/api/track/v1/reference/details/" . referenceNumber . "?" . http_build_query($query),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$error = curl_error($curl);

curl_close($curl);

if ($error) {
  echo "cURL Error #:" . $error;
} else {
  echo $response;
}

If in the $query data, I use

  "refNumType" => "SmallPackage",

I get

{"trackResponse":{"shipment":[{"inquiryNumber":"657780","warnings":[{"code":"TX0002","message":"Tracking Information Not Available at this time"}]}]}}

and if I use

  "refNumType" => "fgv",

I get

{"trackResponse":{"shipment":[{"warnings":[{"code":"TW0001","message":"Tracking Information Not Found"}]}]}}

I'm not sure what I am doing wrong.

Possibly useful detail: the orders are shipped using UPS Worldship, and that's where the order numbers are specified.

Solution

The UPS Track by Reference Number API does not properly document the fromPickUpDate and toPickUpDate parameters:

fromPickUpDate
Default: "currentDate-14"

toPickUpDate
Default: "currentDate"

The actual date format is not specified.

In a PHP library implementing the legacy XML version of the API, we can see that the parameters use the Ymd format (source):

$beginDate = $this->beginDate->format('Ymd');
$endDate = $this->endDate->format('Ymd');

The REST API uses the same format.