# Earliest possible delivery date

This endpoint provides the earliest possible delivery date for an item or a list of items. This information can be used on a search result or product overview page to inform the shop user about the earliest delivery date that can be expected for a specific item.

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

{% hint style="warning" %}
**Limitations and mandatory configurations**

* The maximum number of days that are checked is limited to **45 days**.
* Since the endpoint checks for delivery days, it is mandatory to have transit times configured per carrier.
* When defined for the tenant, [average fulfillment duration](https://docs.fulfillmenttools.com/documentation/getting-started/facilities/managed-facilities#facilities-averagefulfillmentduration), [fulfillment times](https://docs.fulfillmenttools.com/documentation/getting-started/facilities/managed-facilities#facilities-fulfillmenttimes) of the facilities, and [carrier capacities](https://docs.fulfillmenttools.com/documentation/getting-started/facilities/managed-facilities#carrier) are included in the calculation.
  {% endhint %}

## Request and response

### **Request**

* **`earliestDeliveryDate:`** Set to "now" by default, meaning the customer is interested in an ASAP delivery. If a different future date is specified, available delivery dates will be checked starting from that point in time (i.e., the user does not want to receive their order before a given date).
* **`tenantArticleIds:`** The earliest delivery date can be calculated for a single item or a list of items. If a list of items is requested, the calculation is done for each item individually (**not as a basket**).
* **`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.
* **`filter:`** Since the request does not check for fences it is possible to include filters referring to [custom attributes](https://docs.fulfillmenttools.com/documentation/getting-started/custom-attributes). If the request contains a filter with a custom attribute only those facilities are checked which also have the matching custom attribute attached to the facility entity.

### **Response**

The response contains a list of the requested items with:

* **`earliestPredictedDeliveryDate:`** Earliest point in time when the user can expect this particular item to be delivered in case the order would be placed at this moment.
* **`availableCarrier:`**
  * **`name:`** Name of the carrier (key) like "DHL"
  * **`nonDeliveryDays:`** regions where this particular date is a non-delivery date of the corresponding carrier (for example, DE-NW: DHL does not deliver on 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 %}

## Get earliest delivery

> Get earliest delivery timepoint for a given checkoutOption

```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":{"CheckoutOptionsDeliveryEarliestRequest":{"properties":{"consumerAddress":{"allOf":[{"$ref":"#/components/schemas/CheckoutOptionsConsumerAddress"}],"description":"Consumer delivery address"},"earliestDeliveryDate":{"description":"Earliest delivery date","format":"date-time","type":"string"},"filter":{"allOf":[{"$ref":"#/components/schemas/CheckoutOptionsFacilityFilter"}],"description":"Facility filter criteria"},"includeCalculationHints":{"description":"Whether to include calculation hints in the response","type":"boolean"},"includeListingDetails":{"description":"Indicates whether listing-related details should be included in the response. If set to `true`, the response contains additional listing details. Defaults to `false`.","type":"boolean"},"tenantArticleIds":{"description":"List of tenant article IDs","items":{"type":"string"},"minItems":1,"type":"array"}},"required":["consumerAddress","tenantArticleIds"],"title":"CheckoutOptionsDeliveryEarliestRequest","type":"object","description":"CheckoutOptionsDeliveryEarliestRequest"},"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"},"CheckoutOptionsFacilityFilter":{"properties":{"customAttributes":{"description":"Custom attributes for facility filtering","type":"object"},"tags":{"items":{"$ref":"#/components/schemas/TagReference"},"type":"array"}},"title":"CheckoutOptionsFacilityFilter","type":"object","description":"CheckoutOptionsFacilityFilter"},"TagReference":{"properties":{"id":{"type":"string"},"value":{"type":"string"}},"required":["value","id"],"title":"TagReference","description":"TagReference"},"CheckoutOptionsDeliveryEarliestResponse":{"properties":{"calculationHints":{"description":"Calculation hints for debugging","items":{"type":"string"},"type":"array"},"checkoutOptions":{"description":"List of checkout options for each article","items":{"$ref":"#/components/schemas/CheckoutOptionsDeliveryEarliestResponseItem"},"type":"array"}},"required":["checkoutOptions"],"title":"CheckoutOptionsDeliveryEarliestResponse","type":"object","description":"CheckoutOptionsDeliveryEarliestResponse"},"CheckoutOptionsDeliveryEarliestResponseItem":{"properties":{"availableCarriers":{"description":"Available carriers for delivery","items":{"$ref":"#/components/schemas/CheckoutOptionsDeliveryEarliestResponseItemAvailableCarrier"},"type":"array"},"availableFacilityConnections":{"description":"Available facility connections","items":{"$ref":"#/components/schemas/CheckoutOptionsDeliveryEarliestResponseItemAvailableConnection"},"type":"array"},"earliestPredictedDeliveryDate":{"description":"Earliest predicted delivery date","format":"date-time","type":"string"},"listingDetails":{"description":"Listing details","items":{"$ref":"#/components/schemas/CheckoutOptionsListingDetails"},"type":"array"},"tenantArticleId":{"description":"Tenant article ID","type":"string"}},"required":["tenantArticleId"],"title":"CheckoutOptionsDeliveryEarliestResponseItem","type":"object","description":"CheckoutOptionsDeliveryEarliestResponseItem"},"CheckoutOptionsDeliveryEarliestResponseItemAvailableCarrier":{"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":"CheckoutOptionsDeliveryEarliestResponseItemAvailableCarrier","type":"object","description":"CheckoutOptionsDeliveryEarliestResponseItemAvailableCarrier"},"CheckoutOptionsDeliveryEarliestResponseItemAvailableConnection":{"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":"CheckoutOptionsDeliveryEarliestResponseItemAvailableConnection","type":"object","description":"CheckoutOptionsDeliveryEarliestResponseItemAvailableConnection"},"CheckoutOptionsListingDetails":{"properties":{"customAttributes":{"additionalProperties":true,"description":"Custom attributes associated with the listing","type":"object"},"facilityRef":{"description":"Facility reference of the listing","type":"string"},"tenantFacilityId":{"description":"Tenant facility id of the listing","type":"string"}},"required":["facilityRef","tenantFacilityId"],"title":"CheckoutOptionsListingDetails","type":"object","description":"CheckoutOptionsListingDetails"},"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/earliest":{"post":{"deprecated":false,"description":"Get earliest delivery timepoint for a given checkoutOption","operationId":"checkoutoptionDeliveryEarliest","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutOptionsDeliveryEarliestRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutOptionsDeliveryEarliestResponse"}}},"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 earliest delivery","tags":["Checkout Options (DOMS)"]}}}}
```