Predict an order's delivery date

🚧

A new version of the docs is available here

General

To predict an order's delivery date we will use the fetchPrediction method that:

  • calls the Shipup API using the machine learning model
  • populates HTML elements that match shipup data-attributes or the custom css selector
  • returns the API response

You will find below different examples of usage of the fetchPrediction method and the reference definition

Examples

Simple

If you don't provide any carriers in the request, all carrier services that you have configured in Shipup will be available in the response.

ShipupETA.init({ publicApiKey: 'my-api-key' }).fetchPredictions()
	.then(predictions => {
		console.log('Predictions', predictions);
	})
	.catch(error => {
		console.error('Error', error)
	})

Override default parameters

You can also override the default request payload by specifying it:

ShipupETA.init({ publicApiKey: 'my-api-key' }).fetchPredictions({
  destination: {
    country_code: 'FR',
  },
  carriers: [
    {
      service_code: 'base',
      code: 'ups',
    },
  ],
})
	.then(predictions => {
		console.log('Predictions', predictions)
	})
	.catch(error => {
		console.error('Error', error)
	})

Using shipup data attributes

Note that when the carrier_service you want to obtain predictions for is the 'base' carrier_service for the carrier, you'll set the carrier_code as value for the data-attribute instead of 'base' (we have data-shipup-eta-carrier-service="colissimo"in the example below). For all other carrier services, use the carrier service_code as defined in the documentation.

You can use id="data-shipup-eta-best-carrier" which will place the fastest delivery (the best estimate) provided by a service. This is selected by comparing first the delivery_date, then the safe_delivery_date with each other in that order and selecting the smallest for each date. In the case that there are multiple services that provide the exact same best estimate, the service is randomly selected from those options.

You can also use id="data-shipup-eta-best-cutoff-time" which will place the countdown for the nearest cutoff time, for the carrier service provided in data-shipup-eta-best-carrier. With this, you can set up a countdown like "if you order within 2 hours 14 minutes".

<div>
  Mondial relay : <span data-shipup-eta-carrier-service="mondial_relay">loading...</span>
</div>
<div>
  Colissimo : <span data-shipup-eta-carrier-service="colissimo">loading...</span>
</div>
<div>
  Best : <span id="data-shipup-eta-best-carrier">loading...</span> if you order within <span id="data-shipup-eta-best-cutoff-time">loading...</span>
</div>

<script>
  ShipupETA.init({ publicApiKey: 'my-api-key' }).fetchPredictions()
</script>

Displaying the cutoff time countdown

You can also use dedicated data attributes to display the cutoff time countdown for a specific carrier:

<div>
  Mondial relay: order before <span data-shipup-eta-cutoff-time="mondial_relay">loading...</span>
</div>

<script>
  ShipupETA.init({ publicApiKey: 'my-api-key' }).fetchPredictions()
</script>

In a similar manner, an extra id="data-shipup-eta-best-cutoff-time"is provided to inject the countdown for the best estimate.

ShipupETA.fetchPredictions(options)

Use ShipupETA.fetchPredictions(options) to estimate an order's arrival date.
Returns Promise<PredictionResponse>

⚠️ For retro-compatibility reasons the method returns an array of predictions, enriched with the object properties detailed in the link above.
Manipulating the method response as an array is deprecated and will be removed in future versions.

Additionally, fetchPredictions will find all DOM nodes that match the data-shipup-eta-carrier="carrier_name" rule or that match the carrierCodesCssSelectorsMapping defined for this carrier and replace their inner HTML by the estimated date of arrival in the DOM, using the language configured in the language parameter of ShipupETA.init method.

Options input:

FIELDDESCRIPTION
options.origin
address, optional
Package shipping origin (e.g. warehouse location)
options.destination
address, optional
Package destination address (e.g. recipient address).
ShipupETA.destinationAddress will be used if not provided
options.carriers
carrier[], optional
List of carriers and services to return predictions for.
By default, all carriers added on your Shipup account will be used if not provided.
options.order
order, optional
Order specific details.

API Object reference

πŸ“˜

The object reference for the delivery date estimation ShipupETA JS library is the same as for the API. Both object references are available in the ShipupETA documentation.