> For the complete documentation index, see [llms.txt](https://docs.parcellab.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parcellab.com/docs/developers/v2/promise/promise-dates.md).

# Promise Dates

Use the Promise API to get an estimated delivery date to display during conversion and checkout to reduce uncertainty that leads to cart abandonment and improve customer delivery satisfaction.

## Overview

parcelLab provides an API you can call to get forecasted delivery dates. This date can be used to display a delivery date promise on the product details page or at checkout. It can be shown in a format you want on your website so customers can see when a product should arrive before buying it.

{% hint style="info" %}
For more information on the scope and requirements of this feature, please contact your parcelLab representative.
{% endhint %}

## Get Promise Date

Details of how the `v2/prediction` endpoint can be used to generate a forecasted delivery date in the parcelLab system are described below.

### Request Parameters

Call `GET https://api.parcellab.com/v2/prediction`. This storefront endpoint uses the `user` query parameter to select a Promise-enabled account. It does not require an API token in the URL or headers.

| Parameter             | Use                                                                                                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user`                | Required. Your parcelLab account ID.                                                                                                                                                  |
| `destination`         | Required. ISO 3166-1 alpha-3 country code, such as `GBR`; `<postal_code>_<country_code>`, such as `SW1A1AA_GBR`; or the shopper's IPv4 or IPv6 address.                               |
| `fallbackCountry`     | Optional. A three-letter country code, such as `USA`, used when an IP destination cannot resolve or has no matching delivery methods. Only valid with an IP address in `destination`. |
| `warehouse`           | Optional. Warehouse name, ID, or configured alias.                                                                                                                                    |
| `courier`             | Optional. Carrier code or configured alias.                                                                                                                                           |
| `courierServiceLevel` | Optional. A service-level value configured for the delivery method.                                                                                                                   |
| `lang`                | Optional. Language for localized result text.                                                                                                                                         |

The warehouse, carrier, and service-level filters accept comma-separated values. Multiple values within one filter are alternatives; different filters must all match. Use values from your Promise configuration.

### Postal Codes with Spaces

For `GET /v2/prediction`, format `destination` as `<postal-code>_<COUNTRY>`, using the uppercase three-letter country code. Keep leading zeros. You can send the postal code with or without spaces and punctuation: the API removes every character except letters, digits, and `_` before it validates the value.

| Address postal code | Country        | `destination` value |
| ------------------- | -------------- | ------------------- |
| `SW1A 1AA`          | United Kingdom | `SW1A1AA_GBR`       |
| `K1A 0B1`           | Canada         | `K1A0B1_CAN`        |
| `02108`             | United States  | `02108_USA`         |
| `02108-1234`        | United States  | `021081234_USA`     |

For example:

```
https://api.parcellab.com/v2/prediction?user=YOUR_ACCOUNT_ID&destination=SW1A1AA_GBR
```

`SW1A 1AA_GBR` and `SW1A1AA_GBR` resolve to the same destination, as do `02108-1234_USA` and `021081234_USA`. For a nine-digit US ZIP code, only the first five digits are used. If you send a space, URL-encode it, for example `destination=SW1A%201AA_GBR`, or use your HTTP client's query-parameter encoder. The compact values above need no space encoding. Keep postal codes as strings and retain normal formatting in customer addresses.

Replace `YOUR_ACCOUNT_ID` with your Promise-enabled account ID.

### Use an IP Address

Before the shopper supplies a delivery address, you can send their IPv4 or IPv6 address in `destination`. For example:

```
https://api.parcellab.com/v2/prediction?user=YOUR_ACCOUNT_ID&destination=8.8.8.8
```

For IPv6, use your HTTP client's query-parameter encoder. For example, `2001:4860:4860::8888` becomes:

```
https://api.parcellab.com/v2/prediction?user=YOUR_ACCOUNT_ID&destination=2001%3A4860%3A4860%3A%3A8888
```

These are example IP addresses. Replace them with the shopper's IP address. The API uses the country and postal code from the IP lookup with the same location rules as an explicit destination. If the lookup returns a country without a postal code, the API uses a country-level location. Successful IP lookups can be reused for up to six hours.

IP geolocation estimates a location. It does not confirm the delivery address. Use an explicit country and postal code when the shopper supplies them, and request a new prediction.

#### Set a Fallback Country

To use a country-level location when the IP lookup fails or has no matching delivery methods, add `fallbackCountry`:

```
https://api.parcellab.com/v2/prediction?user=YOUR_ACCOUNT_ID&destination=8.8.8.8&fallbackCountry=USA
```

The API selects the location as follows:

1. If the IP location has matching delivery methods, the API uses that location. This applies even when the IP resolves to a different country from `fallbackCountry`.
2. If the IP lookup fails or the IP location has no matching delivery methods, the API uses the fallback country. It discards the IP location's postal code and region and selects methods for the country-level location.
3. The API generates predictions for the selected methods. If those methods return no predictions, the API keeps the selected location and returns an empty `prediction` array. An empty generated result does not trigger another fallback.

Your account must have Promise enabled. The warehouse, carrier, and service-level filters also apply to the fallback. A fallback country does not guarantee a prediction.

Use a valid three-letter country code, such as `USA` or `DEU`. Two-letter codes, unknown codes, postal-code destinations, and multiple fallback values are invalid. Supplying `fallbackCountry` with an explicit country or postal-code destination returns HTTP `400`. Remove `fallbackCountry` when you switch to an explicit destination.

Without `fallbackCountry`, an IP lookup that cannot resolve a valid location returns HTTP `404`. A resolved location with no matching delivery methods returns HTTP `200` with `success: true` and an empty `prediction` array.

### Recommended Widget Usage with IP Addresses

For installation, configuration, styling, and the JavaScript API, see the [Promise UI Plugin guide](https://app.gitbook.com/s/ew6OnyRUe6InzC96WnMr/promise/ui-plugin).

The [Promise UI reference implementation](https://github.com/parcelLab/parcellab-embedded-ui-snippets/blob/main/packages/promise-ui/README.md#recommended-usage) provides an embeddable widget that calls this API. Use the examples below for a product detail page or checkout.

Replace `YOUR_ACCOUNT_ID` with your parcelLab account ID. Set `data-country` to the three-letter country code for your main customer market. For an IP request, the widget sends this value as `fallbackCountry`.

If you already have the shopper's delivery address, set `data-postal-code` and `data-country` to that address. A supplied postal code takes priority over IP Fetch. Otherwise, leave `data-postal-code` empty. The widget first checks for a saved shopper selection, then uses IP Fetch. If the public IP lookup fails, it requests a prediction for the configured country.

Load the production script once per page.

With IP Fetch enabled, the widget gets the shopper's public IP from `https://api64.ipify.org` and sends it to the Promise API. If your site uses a Content Security Policy, allow that host and `https://api.parcellab.com` in `connect-src`.

The screenshots show example predictions. Dates, cutoff times, carriers, and locations depend on the API response.

#### Product Detail Page: Estimate with Cutoff

Show the earliest estimated delivery date and the order cutoff. Hide the carrier and location controls to keep the widget small. The widget still uses the known, saved, resolved, or fallback destination.

<figure><img src="https://1304161830-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fm5MUhYrMmT0cei4QdxGn%2Fuploads%2Fgit-blob-c1006431af88c69f478f298faf34016a217c55c0%2Fpromise-ui-pdp-minimal.png?alt=media" alt="Product page estimate with a calendar icon, earliest delivery date, and order cutoff. Location controls are hidden."><figcaption><p>A compact delivery estimate for a product detail page.</p></figcaption></figure>

```html
<div
  data-promise
  data-account-id="YOUR_ACCOUNT_ID"
  data-country="DEU"
  data-postal-code=""
  data-ip-fetch="true"
  data-layout="text"
  data-date-mode="from"
  data-zip-picker="none"
  data-country-picker="false"
  data-show-cutoff="always"
  data-locale="en"
  data-icon="calendar"
  data-confidence="estimated"
  data-date-format="long"
  data-show-carrier="none"
  data-require-zip="false"
  data-selection-reference-date="earliest"
  data-selection-pick="earliest"
></div>
<script src="https://cdn.parcellab.com/js/promise-ui/v1/promise.iife.js" defer></script>
```

#### Checkout: Editable Location and Delivery-by Date

Show the postal code and country from the IP response and let the shopper change them. The location icon marks an approximate location based on IP data or the fallback country. If no postal code is available, the widget shows the country and **Add ZIP**. Supply the checkout address instead when it is known.

Show the selected delivery method's latest estimated arrival date with "delivery by" wording and the carrier name. Hide the cutoff during checkout.

Replace the three `SELECTED_*` values below with the configured carrier, service level, and warehouse for the selected checkout shipping option. Initialize the widget only after that option is known. Use filters that identify that method, rather than a list of available methods.

<figure><img src="https://1304161830-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fm5MUhYrMmT0cei4QdxGn%2Fuploads%2Fgit-blob-a9eb971d758f134b29306b26d6e3dcf04d0ce9ba%2Fpromise-ui-checkout-location.png?alt=media" alt="Checkout estimate with a delivery-by date, UPS carrier name, editable ZIP 10013 and United States, and an approximate-location icon."><figcaption><p>A checkout delivery estimate with an editable destination.</p></figcaption></figure>

```html
<div
  data-promise
  data-account-id="YOUR_ACCOUNT_ID"
  data-courier="SELECTED_COURIER"
  data-service-level="SELECTED_SERVICE_LEVEL"
  data-warehouse="SELECTED_WAREHOUSE"
  data-country="DEU"
  data-postal-code=""
  data-ip-fetch="true"
  data-layout="text"
  data-date-mode="by"
  data-zip-picker="inline"
  data-country-picker="true"
  data-show-cutoff="never"
  data-locale="en"
  data-icon="none"
  data-confidence="estimated"
  data-date-format="short"
  data-show-carrier="inline"
  data-require-zip="false"
  data-selection-reference-date="earliest"
  data-selection-pick="earliest"
></div>
<script src="https://cdn.parcellab.com/js/promise-ui/v1/promise.iife.js" defer></script>
```

The product-page example selects the method with the earliest `earliest` date. The checkout example restricts the request to the selected shipping option and displays its latest date. `data-date-mode="by"` controls the displayed date; it does not select the shipping option.

For checkout changes, initialize through the [JavaScript API](https://docs.parcellab.com/docs/developers/promise/ui-plugin#installation) with the same settings and retain the returned `widget` instance. In your checkout's shipping-selection handler, call `update()` with all three filters together. Here, `selectedShippingOption` is your checkout's mapping to configured Promise values:

```javascript
await widget.update({
  courier: selectedShippingOption.courier,
  serviceLevel: selectedShippingOption.serviceLevel,
  warehouse: selectedShippingOption.warehouse
});
```

Changing HTML attributes alone does not update an active widget. If the selected option has no matching prediction, omit its delivery date instead of removing the filters to show another method.

Shopper changes through the ZIP or country controls skip further IP lookups. A country change clears the previous ZIP. The widget saves these manual selections for 30 days after the last change and reuses them on later visits when the page supplies no postal code. Public IP values and automatic locations are not saved in browser storage.

### Select a Prediction

The `prediction` array can contain several delivery methods. Select the entry that matches the warehouse, carrier, and service level offered at checkout. The first entry is not a guarantee of the fastest or preferred service. Check `success` and whether the array contains a matching entry before displaying a date. An empty array has no date to display.

### Integration Flow: Send, Read, and Save

| Stage                                      | Send or read                                                                                                                                                   | What your integration does                                                                                                                                        |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Estimate before an address is known        | Send `user`, `destination=<shopper-IP>`, and optionally `fallbackCountry`.                                                                                     | Read `location.country` and `location.zip` to show an approximate destination. Keep it separate from the delivery address.                                        |
| Shopper supplies or confirms a destination | Send `destination=<postal-code>_<ISO3-country>`, or only the country if no postal code is available. Remove `fallbackCountry`.                                 | Save a manual country and postal-code choice together if you want to reuse it. Clear the previous postal code when the country changes. Request a new prediction. |
| Display a matching shipping option         | Read the selected `prediction[]` entry's `prediction.earliest`, `latest`, or `mostLikely`.                                                                     | Use `latest` for "delivery by", or `earliest` and `latest` from the same entry for a range. Select the method offered at checkout.                                |
| Shopper places the order                   | Save the displayed ISO date or range, selected method, confirmed destination, and top-level `requestId` with the order.                                        | Keep the promise shown at checkout. Do not replace it silently with a later prediction.                                                                           |
| Create a v2 tracking                       | Send the saved date as `announced_delivery_date` and the saved request ID as `customFields.requestID` if this custom field is configured for your integration. | Use your normal authenticated tracking integration. The prediction request does not create a tracking or save the promise on the order.                           |

Use the confirmed checkout address ahead of saved choices or IP estimates. Request a new prediction when the destination or shipping method changes and before the order is placed. Save ISO dates rather than localized text or cutoff durations. Treat `location.zip` values of `null` or `"0"` as no postal code. If no matching prediction is available, omit the date and let the shopper correct the destination.

The reference widget saves manual destination choices for 30 days, but it does not save the checkout promise to your order system. Its public API does not expose the selected prediction or response request ID. Use a custom API integration or extend the reference implementation to retain these values for the order. A custom integration must also manage destination storage itself. Keep automatic IP locations in temporary page state. See the [product flow and field mapping](https://docs.parcellab.com/docs/convert/promise#using-promise-dates-in-communications-from-parcellab), including how to send a v2 prediction through the v4 Order API.

### Result Structure

Successful responses contain a `prediction` array. Every response from this endpoint includes `location`, which is either a resolved location or `null`. The `requestId` is for tracing and troubleshooting purposes only.

For example, this response shows a resolved location with no predictions:

```json
{
  "requestId": "abcd1234",
  "location": {
    "country": "DEU",
    "region": "DE-BY",
    "zip": "80469"
  },
  "success": true,
  "prediction": []
}
```

| Location field | Type           | Description                                                                                                                                           |
| -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `country`      | String         | Resolved ISO 3166-1 alpha-3 country code, such as `DEU`.                                                                                              |
| `region`       | String         | Resolved region used to select delivery methods, such as `DE-BY`. For a country-level location, this is the two-letter country code, such as `DE`.    |
| `zip`          | String or null | Normalized postal code. A country-level location uses `null` for countries with postal-code validation, or the string `"0"` for countries without it. |

For IP and explicit destinations, `location` shows the location used to select delivery methods. When the fallback is used, it shows the fallback location. For example, a `USA` fallback has `country: "USA"`, `region: "US"`, and `zip: null`.

`location` is `null` before destination resolution or if resolution fails. If an error occurs after resolution, the response retains the resolved location. A non-null location does not guarantee a prediction or a successful response.

Each entry in the prediction array represents one delivery method, including a delivery prediction like the following structure:

```json
{ 
  "id": "Delivery Method ID", 
  "warehouse": "Warehouse ID", 
  "courier": "parcelLab courier code, e.g. ups", 
  "courierName": "Pretty courier name", 
  "courierAlias": [ "Retailer internal courier codes" ],
  "courierServiceLevel": [ "all specified aliases for the service level" ], 
  "globalCourierServiceLevel": "Global service level of the delivery method",
  "prediction": { 
    "min": 1, 
    "max": 2, 
    "likely": 2,
    "send_date": "2022-06-11", 
    "earliest": "2022-06-12", 
    "latest": "2022-06-13", 
    "mostLikely": "2022-06-13", 
    "earliestLocale": "Thursday, Jun 12th, 2022", 
    "latestLocale": "Friday, Jun 13th, 2022", 
    "mostLikelyLocale": "Friday, Jun 13th, 2022", 
    "cutoff": 747, 
    "cutoffLocale": "12 hours" 
  } 
} 
```

#### Delivery Prediction Details

The details included in a delivery prediction are described in the following table.

<table><thead><tr><th width="182">Key</th><th width="216.53846153846155">Type</th><th>Description</th></tr></thead><tbody><tr><td>min</td><td>Integer</td><td>The minimum number of expected courier working days until delivery.<br><strong>Note:</strong> The value for minimum and maximum can be equal.</td></tr><tr><td>max</td><td>Integer</td><td><p>The maximum number of expected courier working days until delivery.</p><p><strong>Note:</strong> The value for minimum and maximum can be equal.</p></td></tr><tr><td>likely</td><td>Integer</td><td>The most likely number of expected courier working days until delivery.</td></tr><tr><td>send_date</td><td><a href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO 8601 date format</a>: YYYY-MM-DD</td><td>The date of dispatch as per warehouse configuration.</td></tr><tr><td>earliest</td><td><a href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO 8601 date format</a>: YYYY-MM-DD</td><td>The earliest expected delivery date taking into consideration working days of the courier, holidays in the destination, and warehouse cut-off and handling times.</td></tr><tr><td>latest</td><td><a href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO 8601 date format</a>: YYYY-MM-DD</td><td>The latest expected delivery date taking into consideration working days of the courier, holidays in the destination, and warehouse cut-off and handling times.</td></tr><tr><td>mostLikely</td><td><a href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO 8601 date format</a>: YYYY-MM-DD</td><td>The most likely individual date of delivery.</td></tr><tr><td>earliestLocale</td><td>Defaults to <code>dddd, MMM DDD, YYYY</code></td><td>Localized representations of the earliest expected delivery date in the specified format.</td></tr><tr><td>latestLocale</td><td>Defaults to <code>dddd, MMM DDD, YYYY</code></td><td>Localized representations of the latest expected delivery date in the specified format.</td></tr><tr><td>mostLikelyLocale</td><td>Defaults to <code>dddd, MMM DDD, YYYY</code></td><td>Localized representations of the most likely delivery date in the specified format.</td></tr><tr><td>cutoff</td><td>Integer</td><td>The time in minutes until cut-off for the estimated delivery dates.</td></tr><tr><td>cutoffLocale</td><td>String</td><td>Localized representations of the cut-off. Can be used within a sentence like "Order within <em>[2 hours | an hour | 20 minutes]</em> to receive your order by <em>[Saturday, Mar 23rd, 2022]</em>".</td></tr></tbody></table>

### Handle Errors and Empty Results

Check both the HTTP status and `success`. An HTTP `200` response can contain `success: false`. Some error responses do not include `prediction`.

| Result                                                                    | HTTP status | Response                                                                                                                              |
| ------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Invalid `fallbackCountry`, or fallback supplied with a non-IP destination | `400`       | `success: false`, `location: null`, and `error: "Invalid fallbackCountry: use an ISO3 country with an IP destination"`.               |
| Account does not have Promise enabled                                     | `401`       | `success: false`, `location: null`, and `error: "Access denied."`. A fallback does not bypass this check.                             |
| Destination cannot resolve, with no fallback supplied                     | `404`       | `success: false`, `location: null`, and `error: "Nothing found."`. This also applies when IP lookup is unavailable.                   |
| No matching methods, or selected methods produce no predictions           | `200`       | `success: true`, the selected `location`, and `prediction: []`.                                                                       |
| Prediction generation fails                                               | `200`       | `success: false`, `error: "Could not generate prediction"`, and `prediction: []`. The response retains `location` if it was resolved. |

If there is no prediction to display, let the shopper enter their country and postal code and request a new prediction without `fallbackCountry`.

### Sample Calls

The sample API calls below show different information in the request (for example: home delivery as the courier service type) for the delivery prediction.

{% tabs %}
{% tab title="Country" %}
Request: `GET https://api.parcellab.com/v2/prediction?user=1612197&destination=DEU`

Example response:

```json
{ 
    "requestId": "wLy6ThLp", 
    "location": { "country": "DEU", "region": "DE", "zip": null },
    "success": true, 
    "prediction": [{ 
        "id": "DHL Standard", 
        "warehouse": "Europe Warehouse",  
        "courier": "dhl-germany", 
        "courierName": "DHL", 
        "courierAlias": [],
        "courierServiceLevel": ["home-delivery","pick-from-store"],
        "prediction": { 
            "min": 1, 
            "max": 3, 
            "likely": 2,
            "send_date": "2023-11-23", 
            "earliest": "2023-11-24", 
            "latest": "2023-11-27", 
            "mostLikely": "2023-11-25",
            "earliestLocale": "Friday, Nov 24th, 2023", 
            "latestLocale": "Monday, Nov 27th, 2023", 
            "mostLikelyLocale": "Saturday, Nov 25th, 2023", 
            "cutoff": 104, 
            "cutoffLocale": "1 hour, 44 minutes"}},
        { 
         "id": "UPS Express",
         "warehouse": "Europe Warehouse",  
         "courier": "ups", 
         "courierName": "UPS", 
         "courierAlias": [],
         "courierServiceLevel": ["home-delivery","express","overnight"],
         "prediction": { 
             "min": 1, 
             "max": 1, 
             "likely": 1,
             "send_date": "2023-11-23", 
             "earliest": "2023-11-24", 
             "latest": "2023-11-24", 
             "mostLikely": "2023-11-24", 
             "earliestLocale": "Friday, Nov 24th, 2023", 
             "latestLocale": "Friday, Nov 24th, 2023",
             "mostLikelyLocale": "Friday, Nov 24th, 2023", 
             "cutoff": 76, 
             "cutoffLocale": "1 hour, 16 minutes"
      }
  }]
}
```

{% endtab %}

{% tab title="Country and Zip Code" %}
Request: `GET https://api.parcellab.com/v2/prediction?user=1612197&destination=80469_DEU`

Example response:

```json
{ 
    "requestId": "Zgr8YN3w", 
    "location": { "country": "DEU", "region": "DE-BY", "zip": "80469" },
    "success": true, 
    "prediction": [{ 
        "id": "DHL Standard", 
        "warehouse": "Europe Warehouse",  
        "courier": "dhl-germany", 
        "courierName": "DHL", 
        "courierAlias": [],
        "courierServiceLevel": ["home-delivery","pick-from-store"],
        "prediction": { 
            "min": 1, 
            "max": 3, 
            "likely": 2,
            "send_date": "2023-11-23",
            "earliest": "2023-11-24",
            "latest": "2023-11-27",
            "mostLikely": "2023-11-25",
            "earliestLocale": "Friday, Nov 24th, 2023",
            "latestLocale": "Monday, Nov 27th, 2023",
            "mostLikelyLocale": "Saturday, Nov 25th, 2023",
            "cutoff": 104, 
            "cutoffLocale": "1 hour, 44 minutes"}},
        { 
         "id": "UPS Express",
         "warehouse": "Europe Warehouse",  
         "courier": "ups", 
         "courierName": "UPS", 
         "courierAlias": [],
         "courierServiceLevel": ["home-delivery","express","overnight"],
         "prediction": { 
             "min": 1, 
             "max": 1, 
             "likely": 1,
             "send_date": "2023-11-23",
             "earliest": "2023-11-24",
             "latest": "2023-11-24",
             "mostLikely": "2023-11-24",
             "earliestLocale": "Friday, Nov 24th, 2023",
             "latestLocale": "Friday, Nov 24th, 2023",
             "mostLikelyLocale": "Friday, Nov 24th, 2023",
             "cutoff": 76, 
             "cutoffLocale": "1 hour, 16 minutes"
       }    
  }]
}
```

{% endtab %}

{% tab title="Specific Service Types" %}
Request: `GET https://api.parcellab.com/v2/prediction?user=1612197&destination=USA&courierServiceLevel=home-delivery`

Example response:

```json
{ 
    "requestId": "gxFAiZfP", 
    "location": { "country": "USA", "region": "US", "zip": null },
    "success": true, 
    "prediction": [{ 
        "id": "USPS Standard", 
        "warehouse": "US East Coast Warehouse",  
        "courier": "usps", 
        "courierName": "USPS", 
        "courierAlias": [],
        "courierServiceLevel": ["home-delivery","pick-from-store"],
        "prediction": { 
            "min": 3, 
            "max": 5, 
            "likely": 4, 
            "send_date": "2022-08-19", 
            "earliest": "2022-08-24", 
            "latest": "2022-08-26", 
            "mostLikely": "2022-08-25",
            "earliestLocale": "Wednesday, Aug 24th, 2022", 
            "latestLocale": "Friday, Aug 26th, 2022", 
            "mostLikelyLocale": "Thursday, Aug 25th, 2022", 
            "cutoff": 1236, 
            "cutoffLocale": "21 hours" 
      } 
  }]
}
```

{% endtab %}
{% endtabs %}

For an IP request with `fallbackCountry=USA`, the following example shows a fallback that has no matching delivery methods. The API still returns the country-level location:

```json
{
  "requestId": "abcd5678",
  "location": {
    "country": "USA",
    "region": "US",
    "zip": null
  },
  "success": true,
  "prediction": []
}
```

### Calculating Delivery Dates for Orders with Known Dispatch Date

For orders where you know the actual dispatch date, you can calculate accurate delivery dates based on when the order will ship. This is useful for scenarios where:

* An order's dispatch date is confirmed after placement
* You need to provide customers with updated delivery expectations based on actual shipment dates
* Customer service agents need to communicate accurate timelines for existing orders

**How It Works**

To calculate a delivery date for an already placed order when you know the dispatch date, use these two parameters together:

1. `_now=<date>` - set this to the known dispatch date/time in ISO 8601 UTC format (for example: `2025-07-01T16:00:00.000Z`)
2. `dispatchNow=true` - this forces the API to skip warehouse cutoff calculations and calculate the delivery date as if the parcel ships at the exact time specified in `_now`

{% hint style="warning" %}
The `_now` timestamp must be in UTC (Zulu time), not local time. Always include the `Z` suffix or `.000Z` to indicate UTC.
{% endhint %}

{% hint style="info" %}
When using `dispatchNow=true` with a specific `_now` value for already placed orders, the `cutoff` will be 0 as you're bypassing warehouse calculations and calculating delivery based on the known dispatch time.
{% endhint %}

### Testing Your Promise Configuration

To preview saved but unpublished changes to your Promise configuration in a staging environment:

1. Integrate the Promise API call to your staging environment.
2. Add the query parameter `&draft=true` to your Promise API call.

This will generate a promise date based on your unpublished Promise configuration, that can be used to review the effect of any configuration updates on the frontend of your staging environment.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.parcellab.com/docs/developers/v2/promise/promise-dates.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.