Ctrlk
API documentationIncident managementFeedback
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Endpoint to create a promise order.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

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 promise.

application/json

ResponseForDeliveryPromise

orderRefstringRequired
orderVersionnumberRequired
post/api/promises/deliverypromise
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: 4323

{
  "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
    ],
    "estimatedDeliveryDate": "2020-02-03T09:45:51.525Z",
    "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": "https://example.com/resource",
        "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"
  },
  "pricing": {
    "discounts": [
      {
        "nameLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "code": "text",
        "context": "text",
        "name": "text",
        "percentage": 1,
        "tenantDiscountId": "text",
        "type": "ABSOLUTE",
        "value": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        }
      }
    ],
    "fees": [
      {
        "name": "text",
        "value": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        }
      }
    ],
    "taxes": [
      {
        "ratePercent": 1,
        "scope": "text",
        "taxableValue": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        },
        "type": "text",
        "value": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        }
      }
    ]
  },
  "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-01-01T00:00:00.000Z",
    "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,
  "pricing": {
    "discounts": [
      {
        "nameLocalized": {
          "de_DE": "Wert",
          "en_US": "Value",
          "ru_RU": "значение"
        },
        "code": "text",
        "context": "text",
        "name": "text",
        "percentage": 1,
        "tenantDiscountId": "text",
        "type": "ABSOLUTE",
        "value": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        }
      }
    ],
    "fees": [
      {
        "name": "text",
        "value": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        }
      }
    ],
    "taxes": [
      {
        "ratePercent": 1,
        "scope": "text",
        "taxableValue": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        },
        "type": "text",
        "value": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        }
      }
    ],
    "total": {
      "priceBreakdown": {
        "subTotal": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        },
        "total": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        },
        "totalDiscounts": {
          "breakdown": {
            "lineItemDiscounts": {
              "currency": "EUR",
              "decimalPlaces": 2,
              "value": 1299
            },
            "orderDiscounts": {
              "currency": "EUR",
              "decimalPlaces": 2,
              "value": 1299
            }
          },
          "value": {
            "currency": "EUR",
            "decimalPlaces": 2,
            "value": 1299
          }
        },
        "totalFees": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        },
        "totalLineItemSurcharges": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        },
        "totalTaxes": {
          "currency": "EUR",
          "decimalPlaces": 2,
          "value": 1299
        }
      }
    }
  },
  "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"
      }
    ],
    "priorityRatingResults": [],
    "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"
        },
        "existenceReason": "KEPT_FROM_LAST_RUN",
        "facilityConnectionRef": "f439e7b6-119e-47cc-a263-05a31baea0de",
        "fallbackCosts": {
          "currency": "AED",
          "decimalPlaces": 1,
          "value": 1
        },
        "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",
        "strandId": "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
        },
        "transferGroup": "0_xyz"
      }
    ],
    "validUntil": "2025-02-05T08:45:50.525Z"
  }
}

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.

Copy the orderRef, as you'll need it for later updates.

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.

The orderId is the orderRef you received in the promise 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.

The orderID is the orderRef you received in the promise 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
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)?)?)$
get/api/configurations/promises
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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

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)?)?)$
put/api/configurations/promises
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
}
PreviousCheckout options
NextExternal information lookup

Last updated

Was this helpful?