Status page

Displaying predictions

Suggest Edits

Once the ShipupETA module is correctly configured, the next and last step is to actually display the computed predictions.

Directly using the API result

As detailed in previous sections and in our API Reference, fetchPredictions returns the following object:

{
  "best_estimation": {
    "carrier_code": "carrier_code",
    "service_code": "service_code",
    "delivery_date": "2024-04-19",
    "safe_delivery_date": "2024-04-22",
    "cutoff_datetime_utc": "2024-04-18T13:00:00.000Z"
  },
  "delivery_date_estimations": [
    {
      "carrier_code": "carrier_code",
      "service_code": "service_code",
      "delivery_date": "2024-04-19",
      "safe_delivery_date": "2024-04-22",
      "cutoff_datetime_utc": "2024-04-18T13:00:00.000Z"
    },
    // ...
  ]
}

The delivery_date_estimations property contains all carrier service estimations. The best_estimation picks among that list the service with the best delivery_date.

Each prediction contains three dates:

  • delivery_date: the base delivery estimate
  • safe_delivery_date: a less optimistic estimate ; it adds a one-day delay to the estimation before any post-processing rule is applied
  • cutoff_datetime_utc: the UTC datetime until which the estimation is no longer valid ; it takes into account your warehouse's opening days and cutoff times

All of these dates are ISO 8601 compliant and can be manipulated with generic date management librairies such as Moment.js or Luxon.

Using Shipup data attributes

The module also includes a ready-to-go, opinionated, way to display results using custom data attributes. After a call to fetchPredictions, the module will try to replace the content of any HTML tag with custom data attributes.

For instance:

<span data-shipup-eta-carrier-service="mondial_relay">This content will be replaced<span>

The full list of attributes can be found here.

The available data attributes allow to:

  • display the estimation for each carrier service and the best estimation
  • display the cutoff time countdown

In addition two display parameters are exposed:

  • which language to use (only English, French and Spanish are supported at the moment)
  • how to display estimates (show safe estimate, default estimate or a range between the two)

Let's take time to detail how each of these work.

Choosing the language

When using custom attributes to display results, the module will format times and durations based on the browser language. If that language is not supported, it will fallback to English.

🚧 Only English (en), French (fr) and Spanish (es) are supported at the moment.

For example, it will use the following format to display dates in each language:

  • en (default): Wednesday, April 24th
  • fr: mercredi 24 avril
  • es: miércoles 24º de abril

You can force a specific language when calling ShipupETA.init using the language option:

ShipupETA.init({
  publicApiKey: 'XXX',
  language: 'en' // valid values are 'en' | 'fr' | 'es'
});

Choosing the display mode

When using custom attributes to display results, you can choose between 3 different display modes:

  • early (default): will use the delivery_date date property
  • safe: will use the safe_delivery_date date property ; that estimation adds a one-day delay to the estimation before any post-processing rule is applied
  • range: will display a date range between the early and safe estimates

You can force the mode when calling ShipupETA.init using the estimationMode option:

ShipupETA.init({
  publicApiKey: 'XXX',
  estimationMode: 'early' // valid values are 'early' | 'safe' | 'range'
});

Displaying carrier service estimations

The data attribute to use is data-shipup-eta-carrier-service=XXX.

The value you should provide is:

  • the service's carrier_code when you want to display the estimate for the "base" service
  • the service's service_code otherwise

You can also directly display the best estimate by adding the following id="data-shipup-eta-best-carrier to an HTML tag. This can be useful f.i. when displaying the most optimistic delivery option on a product page.

For instance:

<div>
  Royal Mail base service estimate:
  <span data-shipup-eta-carrier-service="royal_mail">Loading...</span>
</div>
<div>
  Royal Mail 1st class estimate:
  <span data-shipup-eta-carrier-service="royal_mail_1st_class">Loading...</span>
</div>
<div>
  Best estimate:
  <!-- will display the Royal Mail 1st class estimate  -->
  <span id="data-shipup-eta-best-carrier">Loading...</span>
</div>

{
  "best_estimation": {
    "carrier_code": "royal_mail",
    "service_code": "royal_mail_1st_class",
    "delivery_date": "2024-04-18",
    "safe_delivery_date": "2024-04-20",
    "cutoff_datetime_utc": "2024-04-18T13:00:00.000Z"
  },
  "delivery_date_estimations": [
    {
      "carrier_code": "royal_mail",
      "service_code": "base",
      "delivery_date": "2024-04-19",
      "safe_delivery_date": "2024-04-22",
      "cutoff_datetime_utc": "2024-04-18T13:00:00.000Z"
    },
    {
      "carrier_code": "royal_mail",
      "service_code": "royal_mail_1st_class",
      "delivery_date": "2024-04-18",
      "safe_delivery_date": "2024-04-20",
      "cutoff_datetime_utc": "2024-04-18T13:00:00.000Z"
    },
  ]
}

The full list of carrier and service codes can be found in our documentation.

Displaying the cutoff time countdown

The data attribute to use is data-shipup-eta-cutoff-time=XXX.

The value you should provide is:

  • the service's carrier_code when you want to display the cutoff time countdown for the "base" service
  • the service's service_code otherwise

You can also directly display the countdown of the best estimate by adding the following id="data-shipup-eta-best-cutoff-time to an HTML tag.

Using custom CSS selectors

If you already have CSS selectors in place to identify merchants and don't want to use Shipup's custom data attributes, you can override those. To do so, use the carrierCodesCssSelectorsMapping property when calling ShipupETA.init:

<script>
  ShipupETA.init({
    publicApiKey: 'XXX',
    carrierCodesCssSelectorsMapping: {
      mondial_relay: '#custom-random',
      colissimo: '.custom-colissimo',
      colissimo_expert_europe: '.custom-colissimo-service-expert',
    }
  }).fetchPredictions({
    "carriers": [
      { "code": "mondial_relay", service_code: "base" },
      { "code": "colissimo", service_code: "base" },
      { "code": "colissimo", service_code: "colissimo_expert_europe" }
    ]
  });
</script>

<div>
  Mondial Relay: <span id="custom-random">loading...</span>
</div>
<div>
  Colissimo : <span class="custom-colissimo">loading...</span>
</div>
<div>
  Colissimo Expert Europe : <span class="custom-colissimo-service-expert">loading...</span>
</div>

Which solution should I use?

When to use data attributes

Use custom data attributes when:

  • you don't have much customisation to do
  • you are fine with the display format of estimates

Using data attributes is the fastest way to integrate ShipupETA, with the least effort needed from your tech team.

When to directly manipulate raw API responses

Use raw API responses when you need full adaptability on how you display the estimates. A non-exhaustive list of reasons is:

  • you want to support more languages than French, Spanish and English
  • you want to use a different date / time format
  • you make multiple calls to fetchPredictions in the same page for the same carrier

Using API responses requires more effort from your tech team but offers the most flexibility on what you want to do with the estimations.

Updated 2 months ago

What’s Next