Available delivery dates within time-period

What is the purpose of this endpoint?

The purpose of this endpoint is to provide all available delivery dates based on a basket of items within a defined timeframe. This endpoint can be seen as an extension to the "earliest possible delivery date"-endpoint but here we check for multiple days whether a fulfillment plus delivery can be achieved or not.

This information might be used in order to provide a calendar view within the checkout to the user, which indicates the available delivery dates. With this one can make sure that the consumer knows at an early stage of the checkout journey when an item can be delivered and lead the purchase decision.

You find the documentation of this call here.

The length of the time period is restricted to 60 days. Please note that the longer the time period, the more time may be needed to calculate all the results (depending on the size of your fulfillment network).

How does it work?

Some additional info about the request:

• startDate: This is the start date of the requested time range. If no info is given we use the default "now" (timestamp of the request).

• endDate: This is the start date of the requested time range. If no info is given we use the default "now" (timestamp of the request).

• basket:Contains all tenantArticleIds and the respective quantities that the customer is interested in buying

• consumerAddress:The request needs to contain at least the consumer country. This is important, as the nondeliverydays are taken into account when calculating the earliest delivery day and these differ from country to county and also from to region. It also possible to provide a postal code in the request (i.e. for logged in shop users). By doing so, the calculation can also consider region specific non delivery days.

• deliveryPreferences: By setting deliveryPreferences like preferredCarrier(s) or preferredCarrierProductCategories only matching carrier options are considered when evaluating which dates are possible delivery dates.

Some additional info about the response:

• date: Defines the date on which the calculation took place and on which the following information applies

• overallStatus: The result can be be ALL, NONE or PARTIAL. ALL: all items within the requested basket can be delivered at the corresponding date NONE: none of the items within the requested basket can be delivered at the corresponding date. PARTIAL: part of the items within the requested basket can be delivered at the corresponding date.

• availableCarriers:

  • name:Name of the carrier (key) like "DHL"

  • nonDeliveryDays:Regions where this particular date is a non delivery date of the corresponding carrier (i.e. DE-NW: DHL does not deliver on the March 3rd 2025 in North Rhine Westphalia due to carnival)

Please note that the usage of the overallStatusis an aggregate of the basket and used in order to improve the performance of the call. If there is need for more specific information on item level you can request this call multiple times but with only one item in the basket or use our checkout options and promising endpoints.

delivery/timeperiod

POST/api/promises/checkoutoptions/delivery/timeperiod

Body

application/json

startDatestring (date-time)

The start of the evaluated time period. Defaults to "now" (timestamp of the request)

Example: "2024-06-03T00:00:00.000Z"

endDatestring (date-time)

The end of the evaluated time period. Default is the start date + 30 days. Please note that the maximum time period can not exceed 45 days.

Example: "2024-07-13T00:00:00.000Z"

basket*array of BasketItem (object)

Items, that are considered to be delivered together.

consumerAddress*CheckoutOptionsConsumerAddress (object)

deliveryPreferencesDeliveryPreferencesShipping (object)

includeCalculationHintsboolean

Set this flag to true to get additional information about the availability of the requested articles

Response

200400401403

The request could be evaluated.

Body

application/json

checkoutOptions*array of CheckoutOptionsDeliveryTimePeriodResponseItem (object)

calculationHintsarray of string

Hints generated during the calculation of the earliest delivery date. These are only returned if the includeCalculationHints flag was provided when performing the request.

Request

JavaScriptCurlPython

const response = await fetch('/api/promises/checkoutoptions/delivery/timeperiod', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "basket": [
        {
          "tenantArticleId": "DE-ZGT-4711",
          "quantity": 4
        }
      ],
      "consumerAddress": {
        "country": "DE"
      }
    }),
});
const data = await response.json();

Response

200

{
  "checkoutOptions": [
    {
      "overallStatus": "ALL",
      "date": "2020-02-03T00:00:00.000Z",
      "availableCarriers": [
        {
          "name": "DHL",
          "carrierRef": "text",
          "nonDeliveryDays": [
            "DE-NW"
          ]
        }
      ]
    }
  ],
  "calculationHints": [
    "text"
  ]
}