# Availability in delivery time period

This endpoint provides all available delivery dates based on a basket of items within a defined timeframe. This information might be used in order to provide a calendar view to the user that indicates the available delivery dates.

{% hint style="info" %}
More API information can be found here: [REST API documentation – checkoutoptions/delivery/timeperiod](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/promises/checkoutoptions/delivery/timeperiod)
{% endhint %}

{% hint style="warning" %}
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 the results (depending on the size of the fulfillment network).
{% endhint %}

## Request and response

### **Request**

* **`startDate:`** Start date of the requested time range. If no info is given, the default is "now" (timestamp of the request).
* **`endDate:`** End date of the requested time range. If no info is given, the default is "now" (timestamp of the request).
* **`basket:`** Contains all `tenantArticleIds` and the respective quantities that the customer is interested in buying.
* **`consumerAddress:`** The request must include at least the consumer's country. This is important because [non-delivery days](https://docs.fulfillmenttools.com/documentation/store-operations/carrier-management/carrier-features-and-requirements#non-delivery-days) are taken into account when calculating the earliest delivery date, and these vary by country and region. It is also possible to provide a postal code in the request (e.g., for logged-in shop users). Doing so allows considering 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.

### **Response**

* **`date:`** Date on which the calculation took place and for which the below information applies.
* **`overallStatus:`** The result can be ALL, NONE or PARTIAL.
  * **ALL**: all items of the requested basket can be delivered on the corresponding date
  * **NONE**: none of the items of the requested basket can be delivered on the corresponding date
  * **PARTIAL**: part of the items of the requested basket can be delivered on 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 (e.g., DE-NW: DHL does not deliver on the March 3rd 2025 in North Rhine Westphalia due to carnival)

{% hint style="info" %}
[Expected stocks](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock/expected-stock-in-availability) that were announced via [purchase order](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/inbound-process/purchase-order) are also considered in the response. Only purchase orders with `requestedDate.type` "ASAP" are not considered as these deliveries are expected to arrive as soon as possible and there is no exact date that can be used to check the potential availability of these stocks for incoming orders.
{% endhint %}

## POST /api/promises/checkoutoptions/delivery/timeperiod

> Get delivery time period

```json
{"openapi":"3.0.1","info":{"title":"fulfillmenttools","version":"VERSIONLESS"},"tags":[{"description":"Endpoints used by shops to get the current available pickup stores and available service levels like Same-Day delivery.","name":"Checkout Options (DOMS)"}],"servers":[{"url":"https://{tenant}.api.fulfillmenttools.com","variables":{"tenant":{"default":"your-tenant-name"}}}],"security":[{"BearerToken":[]}],"components":{"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CheckoutOptionsDeliveryTimePeriodRequest":{"properties":{"basket":{"description":"Basket items","items":{"$ref":"#/components/schemas/BasketItem"},"type":"array"},"consumerAddress":{"allOf":[{"$ref":"#/components/schemas/CheckoutOptionsConsumerAddress"}],"description":"Consumer delivery address"},"deliveryPreferences":{"$ref":"#/components/schemas/DeliveryPreferencesShipping"},"endDate":{"description":"End date-time of the period","format":"date-time","type":"string"},"includeCalculationHints":{"description":"Whether to include calculation hints in the response","type":"boolean"},"startDate":{"description":"Start date-time of the period","format":"date-time","type":"string"}},"required":["basket","consumerAddress"],"title":"CheckoutOptionsDeliveryTimePeriodRequest","type":"object","description":"CheckoutOptionsDeliveryTimePeriodRequest"},"BasketItem":{"properties":{"quantity":{"description":"Quantity","type":"integer"},"tenantArticleId":{"description":"Tenant article ID","type":"string"}},"required":["tenantArticleId","quantity"],"title":"BasketItem","type":"object","description":"BasketItem"},"CheckoutOptionsConsumerAddress":{"properties":{"addressType":{"description":"Type of address","enum":["POSTAL_ADDRESS","PARCEL_LOCKER","INVOICE_ADDRESS"],"type":"string"},"city":{"description":"City name","type":"string"},"country":{"description":"Country code","type":"string"},"houseNumber":{"description":"House number","type":"string"},"postalCode":{"description":"Postal code","type":"string"},"province":{"description":"Province or state","type":"string"},"street":{"description":"Street name","type":"string"}},"required":["country"],"title":"CheckoutOptionsConsumerAddress","type":"object","description":"CheckoutOptionsConsumerAddress"},"DeliveryPreferencesShipping":{"properties":{"carrierProductCategory":{"$ref":"#/components/schemas/CarrierProductCategory"},"desiredDeliveryTime":{"format":"date-time","type":"string"},"preferredCarriers":{"items":{"$ref":"#/components/schemas/PreferredCarrier"},"type":"array"},"preferredCarriersWithProduct":{"items":{"$ref":"#/components/schemas/PreferredCarrierWithProduct"},"type":"array"},"preselectedFacilities":{"items":{"$ref":"#/components/schemas/PreselectedFacility"},"type":"array"},"serviceLevel":{"description":"DELIVERY: The parcel will reach the recipient according to the cycle time of the carrier, typically 1-3 days when shipping nationaly. SAMEDAY: The parcel will reach the recipient the same day when ordering.","enum":["DELIVERY","SAMEDAY"],"type":"string"}},"type":"object","title":"DeliveryPreferencesShipping","description":"DeliveryPreferencesShipping"},"CarrierProductCategory":{"description":"Desired product class to choose when ordering a label, this is not a carrier specific value","enum":["STANDARD","EXPRESS","VALUE","FORWARDING"],"type":"string","title":"CarrierProductCategory"},"PreferredCarrier":{"description":"Keys of the preferred carriers to handle out the order","type":"string","title":"PreferredCarrier"},"PreferredCarrierWithProduct":{"additionalProperties":false,"properties":{"carrierKey":{"type":"string"},"carrierProduct":{"type":"string"},"carrierServices":{"items":{"$ref":"#/components/schemas/CarrierServices"},"type":"array"}},"required":["carrierKey"],"title":"PreferredCarrierWithProduct","description":"PreferredCarrierWithProduct"},"CarrierServices":{"description":"Services which should be booked from carrier","enum":["SIGNATURE","CUSTOMER_SIGNATURE","ADULT_SIGNATURE","SATURDAY_DELIVERY","IDENTITY_CHECK_COMPANY","IDENTITY_CHECK_PRIVATE","ADDITIONAL_TRANSPORTATION_INSURANCE"],"type":"string","title":"CarrierServices"},"PreselectedFacility":{"anyOf":[{"required":["facilityRef"]},{"required":["tenantFacilityId"]}],"properties":{"facilityRef":{"description":"Reference to the facility which is supposed to fulfill the order.","type":"string"},"tenantFacilityId":{"description":"Reference to the facility which is supposed to fulfill the order.","type":"string"}},"type":"object","title":"PreselectedFacility","description":"PreselectedFacility"},"CheckoutOptionsDeliveryTimePeriodResponse":{"properties":{"calculationHints":{"description":"Calculation hints","items":{"type":"string"},"type":"array"},"checkoutOptions":{"description":"Checkout options across the requested period","items":{"$ref":"#/components/schemas/CheckoutOptionsDeliveryTimePeriodResponseItem"},"type":"array"}},"required":["checkoutOptions"],"title":"CheckoutOptionsDeliveryTimePeriodResponse","type":"object","description":"CheckoutOptionsDeliveryTimePeriodResponse"},"CheckoutOptionsDeliveryTimePeriodResponseItem":{"properties":{"availableCarriers":{"description":"Available carriers for the date","items":{"$ref":"#/components/schemas/CheckoutOptionsDeliveryTimePeriodResponseItemAvailableCarrier"},"type":"array"},"availableFacilityConnections":{"description":"Available facility connections for the date","items":{"$ref":"#/components/schemas/CheckoutOptionsDeliveryTimePeriodResponseItemAvailableConnection"},"type":"array"},"date":{"description":"Date of the option","format":"date-time","type":"string"},"overallStatus":{"description":"Overall availability status for the date","enum":["ALL","PARTIAL","NONE"],"type":"string"}},"required":["overallStatus","date"],"title":"CheckoutOptionsDeliveryTimePeriodResponseItem","type":"object","description":"CheckoutOptionsDeliveryTimePeriodResponseItem"},"CheckoutOptionsDeliveryTimePeriodResponseItemAvailableCarrier":{"properties":{"carrierRef":{"description":"Carrier reference","type":"string"},"latestPickingStartDate":{"description":"Latest picking start date","format":"date-time","type":"string"},"name":{"description":"Carrier name","type":"string"},"nonDeliveryDays":{"description":"Non-delivery days","items":{"type":"string"},"type":"array"}},"required":["carrierRef","name"],"title":"CheckoutOptionsDeliveryTimePeriodResponseItemAvailableCarrier","type":"object","description":"CheckoutOptionsDeliveryTimePeriodResponseItemAvailableCarrier"},"CheckoutOptionsDeliveryTimePeriodResponseItemAvailableConnection":{"properties":{"connectionRef":{"description":"Connection reference","type":"string"},"latestPickingStartDate":{"description":"Latest picking start date","format":"date-time","type":"string"},"nonDeliveryDays":{"description":"Non-delivery days","items":{"type":"string"},"type":"array"}},"required":["connectionRef"],"title":"CheckoutOptionsDeliveryTimePeriodResponseItemAvailableConnection","type":"object","description":"CheckoutOptionsDeliveryTimePeriodResponseItemAvailableConnection"},"ApiError":{"items":{"$ref":"#/components/schemas/ErrorInner"},"type":"array","xml":{"name":"ApiError"},"title":"ApiError","description":"ApiError"},"ErrorInner":{"properties":{"description":{"type":"string"},"requestVersion":{"description":"The version provided within an invalid request.","format":"int64","type":"integer"},"summary":{"type":"string"},"version":{"format":"int64","type":"integer"}},"required":["summary"],"type":"object","title":"ErrorInner","description":"ErrorInner"}}},"paths":{"/api/promises/checkoutoptions/delivery/timeperiod":{"post":{"deprecated":false,"description":"","operationId":"checkoutoptionDeliveryTimePeriod","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutOptionsDeliveryTimePeriodRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutOptionsDeliveryTimePeriodResponse"}}},"description":"The request could be evaluated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Invalid input. See response for details."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Your user is not allowed to operate against this API instance"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"Your user, although recognized, is not authorized to use this"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"The requested entity was not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"description":"A version conflict occurred."}},"summary":"Get delivery time period","tags":["Checkout Options (DOMS)"]}}}}
```