Delivery promise

The delivery promise endpoint supports the last step of the checkout journey. It can be requested when the consumer has already decided on what to buy and is about to make the purchase. At this point, the delivery method (for example, the click-and-collect facility or the consumer's address), the items in the cart, and the delivery preferences are known.

Since all relevant information is known, order routing can already be performed, and a preliminary reservation can be made.

Request and response

When sending a promise order, a routing decision is performed, and the respective stock is reserved. The response provides information on where fulfillment can be performed, when fulfillment is expected to be completed, and when delivery is expected to be completed.

If the consumer decides to buy, the promised order becomes a fulfillment order. If the consumer decides against the purchase, the stock reservation is removed after a configurable timeframe.

Create promise order

post

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

PromiseRequest

customAttributesobjectOptional

Attributes that can be added to the order. These attributes cannot be used within fulfillment processes, but it could be useful to have the informations carried here.

orderDatestring · date-timeRequired

The date this order was created at the supplying system.

Example: 2020-02-03T08:45:50.525Z

statusstring · enumOptional

The state of the order. Initially it is OPEN.

Possible values:

tenantOrderIdstringOptional

Field can be used as a reference number in foreign systems, for example as a reference to the source system's identifier for this order.

Example: R456728546

Responses

201

The order promise was created URL of the order promse.

application/json

400

Invalid input. See response for details

application/json

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

post

/api/promises/deliverypromise

HTTPcURLJavaScriptPython

POST /api/promises/deliverypromise HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 3719

{
  "additionalInfo": {
    "includeListingCustomAttributes": false,
    "resourceInvestment": {
      "level": 0.2
    }
  },
  "consumer": {
    "addresses": [
      {
        "additionalAddressInfo": "to care of: Mrs. Müller",
        "city": "Langenfeld",
        "country": "DE",
        "customAttributes": {},
        "houseNumber": "42a",
        "phoneNumbers": [
          {
            "customAttributes": {},
            "label": "text",
            "type": "MOBILE",
            "value": "text"
          }
        ],
        "postalCode": "40764",
        "province": "NRW",
        "street": "Hauptstr."
      }
    ],
    "consumerId": "e4213a07-f563-46a3-b1ba-4dfeb6abe82a",
    "customAttributes": {},
    "facilityRef": "e4213a07-f563-46a3-b1ba-4dfeb6abe82a",
    "tenantFacilityId": "text"
  },
  "customAttributes": {},
  "customServices": [
    {
      "articleItems": [
        {
          "quantity": 1,
          "tenantArticleRef": "text"
        }
      ],
      "customServiceDefinition": {
        "additionalInformation": [
          {
            "additionalInformationRef": "text",
            "tenantAdditionalInformationId": "text",
            "value": "text"
          }
        ],
        "customAttributes": {},
        "customServiceRef": "text",
        "isBundled": true,
        "tenantCustomServiceId": "text"
      },
      "customServiceItems": [
        {
          "articleItems": [
            {
              "quantity": 1,
              "tenantArticleRef": "text"
            }
          ],
          "customServiceDefinition": {
            "additionalInformation": [
              {
                "additionalInformationRef": "text",
                "tenantAdditionalInformationId": "text",
                "value": "text"
              }
            ],
            "customAttributes": {},
            "customServiceRef": "text",
            "isBundled": true,
            "tenantCustomServiceId": "text"
          },
          "customServiceItems": [
            "[Circular Reference]"
          ]
        }
      ]
    }
  ],
  "deliveryPreferences": {
    "collect": [
      null
    ],
    "reservationPreferences": {
      "mode": "SCHEDULED",
      "reservationTime": "2020-02-03T09:45:51.525Z"
    },
    "shipping": {
      "carrierProductCategory": "STANDARD",
      "desiredDeliveryTime": "2020-02-03T09:45:51.525Z",
      "preferredCarriers": [
        "text"
      ],
      "preferredCarriersWithProduct": [
        {
          "carrierKey": "DPD",
          "carrierProduct": "WORLDWIDE",
          "carrierServices": [
            "SIGNATURE"
          ]
        }
      ],
      "preselectedFacilities": [
        null
      ],
      "serviceLevel": "DELIVERY"
    },
    "sourcingOptionRefs": [
      "928f3730-bc48-4d85-b83f-3fd86b776178"
    ],
    "supplyingFacilities": [
      "928f3730-bc48-4d85-b83f-3fd86b776178"
    ],
    "targetTime": "2020-02-03T09:45:51.525Z"
  },
  "orderDate": "2020-02-03T08:45:50.525Z",
  "orderLineItems": [
    {
      "allowedSubstitutes": [
        {
          "attributes": [
            {
              "valueLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "keyLocalized": {
                "de_DE": "Wert",
                "en_US": "Value",
                "ru_RU": "значение"
              },
              "category": "descriptive",
              "context": {
                "type": "FACILITY_GROUP",
                "value": "text"
              },
              "key": "%%subtitle%%",
              "priority": 100,
              "type": "STRING",
              "value": "585er Gold"
            }
          ],
          "imageUrl": "text",
          "measurementUnitKey": "liter",
          "measurementValidation": {
            "overPickHardTolerancePercentage": 20,
            "overPickSoftTolerancePercentage": 15,
            "shortPickHardTolerancePercentage": 15,
            "shortPickSoftTolerancePercentage": 10
          },
          "priority": 1,
          "scannableCodes": [
            "text"
          ],
          "secondaryMeasurementUnitKey": "gram",
          "tenantArticleId": "text",
          "title": "text"
        }
      ],
      "article": {
        "titleLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "customAttributes": {},
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 1,
        "attributes": [
          {
            "valueLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "keyLocalized": {
              "de_DE": "Wert",
              "en_US": "Value",
              "ru_RU": "значение"
            },
            "category": "descriptive",
            "context": {
              "type": "FACILITY_GROUP",
              "value": "text"
            },
            "key": "%%subtitle%%",
            "priority": 100,
            "type": "STRING",
            "value": "585er Gold"
          }
        ]
      },
      "customAttributes": {},
      "measurementUnitKey": "liter",
      "measurementValidation": {
        "overPickHardTolerancePercentage": 20,
        "overPickSoftTolerancePercentage": 15,
        "shortPickHardTolerancePercentage": 15,
        "shortPickSoftTolerancePercentage": 10
      },
      "quantity": 21,
      "scannableCodes": [
        "text"
      ],
      "secondaryMeasurementUnitKey": "liter",
      "secondaryQuantity": 21,
      "shopPrice": 1200,
      "tags": []
    }
  ],
  "paymentInfo": {
    "methodLocalized": {
      "de_DE": "Wert",
      "en_US": "Value",
      "ru_RU": "значение"
    },
    "currency": "EUR"
  },
  "promisesOptions": {
    "validUntil": "2020-02-03T08:45:50.525Z"
  },
  "status": "OPEN",
  "statusReasons": [],
  "stickers": [],
  "tenantOrderId": "R456728546",
  "tags": []
}

{
  "backOrdered": {
    "lineItems": [
      {
        "availabilityTimeframe": {
          "start": "2020-02-03T08:45:50.525Z"
        },
        "available": 1,
        "outOfStockBehaviour": "NONE",
        "quantity": 1,
        "tenantArticleId": "text",
        "title": "text"
      }
    ]
  },
  "collect": {
    "targetTime": "2026-06-06T09:15:12.437Z",
    "facility": {
      "facilityName": "text",
      "facilityRef": "text",
      "tenantFacilityId": "text"
    },
    "lineItems": [
      {
        "availabilityTimeframe": {
          "start": "2020-02-03T08:45:50.525Z"
        },
        "available": 1,
        "outOfStockBehaviour": "NONE",
        "quantity": 1,
        "tenantArticleId": "text",
        "title": "text"
      }
    ]
  },
  "orderRef": "text",
  "orderVersion": 1,
  "promisesOptions": {
    "validUntil": "2020-02-03T08:45:50.525Z"
  },
  "shipToCustomer": [
    {
      "facility": {
        "facilityName": "text",
        "facilityRef": "text",
        "tenantFacilityId": "text"
      },
      "lineItems": [
        {
          "availabilityTimeframe": {
            "start": "2020-02-03T08:45:50.525Z"
          },
          "available": 1,
          "outOfStockBehaviour": "NONE",
          "quantity": 1,
          "tenantArticleId": "text",
          "title": "text"
        }
      ]
    }
  ],
  "shipToStore": [
    {
      "facility": {
        "facilityName": "text",
        "facilityRef": "text",
        "tenantFacilityId": "text"
      },
      "lineItems": [
        {
          "availabilityTimeframe": {
            "start": "2020-02-03T08:45:50.525Z"
          },
          "available": 1,
          "outOfStockBehaviour": "NONE",
          "quantity": 1,
          "tenantArticleId": "text",
          "title": "text"
        }
      ]
    }
  ],
  "sourcingOption": {
    "estimatedDeliveryDate": "2025-02-05T00:00:00.000Z",
    "estimatedPickupDate": "2025-02-05T00:00:00.000Z",
    "id": "text",
    "listingDetails": [],
    "nodes": [
      {
        "facilityRef": "DE-FAC-4711",
        "id": "f439e7b6-119e-47cc-a263-05a31baea0de",
        "isPickUpLocation": true,
        "lineItems": [
          {
            "quantity": 1,
            "tenantArticleId": "text"
          }
        ],
        "tenantFacilityId": "DE-FAC-4711",
        "type": "SUPPLIER"
      }
    ],
    "nonAssignedOrderLineItems": [
      {
        "quantity": 1,
        "tenantArticleId": "text"
      }
    ],
    "ratingResults": [],
    "runId": "text",
    "totalCosts": {
      "salesPrices": [
        {
          "amount": 1,
          "discount": [
            {
              "type": "RELATIVE",
              "value": 7.1
            }
          ],
          "salesPricePerUnitWithDiscountAmount": {
            "currency": "AED",
            "decimalPlaces": 1,
            "value": 1
          },
          "salesPricePerUnitWithoutDiscountAmount": {
            "currency": "AED",
            "decimalPlaces": 1,
            "value": 1
          },
          "sourceFacilityRef": "DE-FAC-4711",
          "sourceTenantFacilityId": "facility-east",
          "tenantArticleId": "DE-ZGT-4711"
        }
      ],
      "totalCosts": {
        "currency": "AED",
        "decimalPlaces": 1,
        "value": 1
      },
      "totalSalesPriceAmount": {
        "currency": "AED",
        "decimalPlaces": 1,
        "value": 1
      },
      "totalShippingCosts": {
        "packageCosts": [
          {
            "costAmount": {
              "currency": "AED",
              "decimalPlaces": 1,
              "value": 1
            },
            "packageName": "Small Box"
          }
        ],
        "totalTransportCostAmount": {
          "currency": "AED",
          "decimalPlaces": 1,
          "value": 1
        }
      }
    },
    "totalPenalty": 187,
    "transfers": [
      {
        "carrier": {
          "carrierKey": "text",
          "carrierName": "text"
        },
        "facilityConnectionRef": "f439e7b6-119e-47cc-a263-05a31baea0de",
        "lineItems": [
          {
            "quantity": 1,
            "tenantArticleId": "text"
          }
        ],
        "packagingInformation": [
          {
            "packagingUnit": {
              "dimensions": {
                "height": 1,
                "length": 1,
                "maxWeightInGram": 1,
                "width": 1
              },
              "maxItemQuantity": 10,
              "name": "Small Box",
              "packagingUnitRef": "text",
              "prices": [
                {
                  "currency": "AED",
                  "decimalPlaces": 1,
                  "value": 1
                }
              ],
              "priority": 1,
              "tenantPackagingUnitId": "text",
              "transitTime": {
                "maxTransitDays": 1,
                "minTransitDays": 1
              },
              "volumeBufferInPercent": 10
            },
            "packedItems": [
              {
                "quantity": 1,
                "tenantArticleId": "text"
              }
            ],
            "totalCosts": {
              "currency": "AED",
              "decimalPlaces": 1,
              "value": 1
            }
          }
        ],
        "sourceNodeRef": "f439e7b6-119e-47cc-a263-05a31baea0de",
        "targetNodeRef": "ad6c5038-15ee-41b8-a180-4c86290d04c3",
        "timeLine": {
          "calculationStartPoint": "2020-02-03T08:45:50.525Z",
          "earliestPickingStart": "2020-02-03T08:45:50.525Z",
          "earliestPossibleDeliveryTime": "2020-02-03T00:00:00.000Z",
          "latestPickingStart": "2020-02-03T08:45:50.525Z",
          "targetTime": "2020-02-03T08:45:50.525Z",
          "usedTransitTimeInDays": 3
        }
      }
    ],
    "validUntil": "text"
  }
}

Since this endpoint can be used in complex networks with combinatorial optimization, a resourceInvestment value can be passed in the request. This parameter accepts values between 0.0 and 1.0 and controls how much time the optimizer has to determine the best result.

For time-critical requests, we recommend a value < 0.5. For non-time-critical requests, we recommend a value of up to 1.0.

To determine the optimal value for your network, contact our support team.

Example uses

When a consumer reaches the final checkout page and enters their details, you can trigger the delivery promise endpoint to create the order in fulfillmenttools with a temporary status of PROMISED. The stock will be reserved, but no pick jobs have been created yet.

Endpoint

POST https://{your-tenant-name}.api.fulfillmenttools.com/api/promises/deliverypromise

Request

Response

Then, multiple scenarios could happen:

• If the consumer submits the order, you could use the CONFIRM_PROMISE action in the order action using the promised order ID, and update the status to OPEN. A pick job will then be created, and the order can be fulfilled.

Endpoint

POST https://{your-tenant-name}.api.fulfillmenttools.com/api/orders/{orderId}/actions

The orderId is the orderRef you received in the promise response.

Request

Response

• If the consumer leaves the checkout without placing an order and doesn't return, you can set a timeframe in the invalidAfterTime field of the promises configuration. This will automatically delete the order, and the stock will be released after this period.

• If the consumer leaves the checkout without placing an order and returns before the defined timeframe has passed, you can use EXTEND_PROMISE in the order action to give the customer more time to complete checkout.

Endpoint

POST https://{your-tenant-name}.api.fulfillmenttools.com/api/orders/{orderId}/actions

The orderID is the orderRef you received in the promise response.

Request

Response

Promises configuration

In the promises configuration, you can define the duration for all promises to be kept. Once this timeframe passes for each promise, the order will be automatically deleted and the stock released.

The time period uses the ISO 8601 duration format. The duration needs to be a multiple of 60 seconds.

The default duration is 8 hours (PT8H).

List promises

get

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Promises configuration was found & you were allowed to access it. The result is in the body.

application/json

PromisesConfiguration

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z

versioninteger · int64Required

The version of the document to be used in optimistic locking mechanisms.

Example: 42

idstringOptional

invalidAfterTimestringRequired

Default amount of time in ISO 8601 duration format after which an promised order becomes invalid and is cancelled. The duration need to be a multiple of 60 seconds.

Default: PT8HPattern: ^P(?:(\d+W)|(\d+Y)?(\d+M)?(\d+D)?(?:T(\d+H)?(\d+M)?(\d+S)?)?)$

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

404

Promises configuration not found

application/json

get

/api/configurations/promises

HTTPcURLJavaScriptPython

GET /api/configurations/promises HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "invalidAfterTime": "PT8H",
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

Change promises config

put

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

PromisesConfiguration

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z

versioninteger · int64Required

The version of the document to be used in optimistic locking mechanisms.

Example: 42

idstringOptional

invalidAfterTimestringRequired

Default amount of time in ISO 8601 duration format after which an promised order becomes invalid and is cancelled. The duration need to be a multiple of 60 seconds.

Default: PT8HPattern: ^P(?:(\d+W)|(\d+Y)?(\d+M)?(\d+D)?(?:T(\d+H)?(\d+M)?(\d+S)?)?)$

Responses

200

The promisesConfiguration was successfully put.

application/json

PromisesConfiguration

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z

lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z

versioninteger · int64Required

The version of the document to be used in optimistic locking mechanisms.

Example: 42

idstringOptional

invalidAfterTimestringRequired

Default amount of time in ISO 8601 duration format after which an promised order becomes invalid and is cancelled. The duration need to be a multiple of 60 seconds.

Default: PT8HPattern: ^P(?:(\d+W)|(\d+Y)?(\d+M)?(\d+D)?(?:T(\d+H)?(\d+M)?(\d+S)?)?)$

400

Invalid input. See response for details

application/json

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

put

/api/configurations/promises

HTTPcURLJavaScriptPython

PUT /api/configurations/promises HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 131

{
  "id": "text",
  "invalidAfterTime": "PT8H",
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

{
  "id": "text",
  "invalidAfterTime": "PT8H",
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}