---
updatedAt: 2026-05-21T12:39:11.000Z
agentTools:
  projectIndex: https://developers.shipup.co/llms.txt
---

# API - Delivery date estimation

## POST /v1/delivery\_date\_estimation

You can query the Shipup API in order to retrieve the Smart Delivery Estimate for a specific order.

**Endpoint:**

* **Description**: Retrieves delivery date estimations for a given order
* **URL**: `https://api.shipup.co/v1/delivery_date_estimation`
* **Method**: POST
* **Headers**: `Authorization: Bearer [PUBLIC_API_KEY]`

> 🚧 API key
>
> Contrary to other API routes, this route requires your **public** API key.\
> You can find it [in your settings page](https://app.shipup.co/settings/general/#apikeys). Keys are located at the bottom of the page.

This endpoint returns a JSON payload containing for each couple of `carrier_code` / `service_code` the most likely delivery date.

## Example of basic request

With an empty payload

```shell
curl -X POST -H "Authorization: Bearer [PUBLIC_API_KEY]" -d "{}" https://api.shipup.co/v1/delivery_date_estimation
```

## Building the payload

On the right, two valid requests and responses are displayed.

> 📘
>
> All request parameters are optional - the more you provide, the more accurate the response will be.
>
> If you don't provide any carriers, the response will include all carrier services that you have configured in Shipup.

```json valid payload
{
  "delivery_date_estimation": {
    "origin": {
      "country_code": "FR",
      "city": "Montpellier"
    },
    "destination": {
      "country_code": "FR",
      "city": "Paris"
    },
    "carriers": [
      {
        "code": "colissimo",
        "service_code": null
      },
      {
        "code": "chronopost",
        "service_code": null
      }
    ]
  }
}
```
```json response
{
  "delivery_date_estimations": [
    {
      "carrier_code": "colissimo",
      "service_code": "base",
      "delivery_date": "2024-02-28",
      "safe_delivery_date": "2024-02-29",
      "cutoff_datetime_utc": "2024-02-26T14:00:00.000Z"
    },
    {
      "carrier_code": "chronopost",
      "service_code": "base",
      "delivery_date": "2024-02-29",
      "safe_delivery_date": "2024-03-01",
      "cutoff_datetime_utc": "2024-02-26T17:00:00.000Z"
    }
  ],
  "best_estimation": {
    "carrier_code": "colissimo",
    "service_code": "base",
    "delivery_date": "2024-02-28",
    "safe_delivery_date": "2024-02-29",
    "cutoff_datetime_utc": "2024-02-26T14:00:00.000Z"
  }
}
```

<div className="block-textarea sidebar">
When the `order.merchant_shipping_date` is specified:
</div>

```json valid payload
{
  "delivery_date_estimation": {
    "origin": {
      "country_code": "FR",
      "city": "Montpellier"
    },
    "destination": {
      "country_code": "FR",
      "city": "Paris"
    },
    "order": {
      "merchant_shipping_date": "2024-07-27"
    },
    "carriers": [
      {
        "code": "colissimo",
        "service_code": null
      }
    ]
  }
}
```
```json response
{
  "delivery_date_estimations": [
    {
      "carrier_code": "colissimo",
      "service_code": "base",
      "delivery_date": "2024-02-28",
      "safe_delivery_date": "2024-02-29",
      "cutoff_datetime_utc": "2024-02-26T14:00:00.000Z"
    }
  ],
  "best_estimation": {
    "carrier_code": "colissimo",
    "service_code": "base",
    "delivery_date": "2024-02-28",
    "safe_delivery_date": "2024-02-29",
    "cutoff_datetime_utc": "2024-02-26T14:00:00.000Z"
  }
}
```