API documentationIncident ManagementFeedback
Edit

Adding facilities

After the environment is set up, facilities can be created using the API. This tutorial demonstrates how to add a facility representing a flagship store in Frankfurt, Germany.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities
{
    "name": "LU.XY Fashion flagship store",
    "address": {
        "companyName": "lu.xy fashion GmbH",
        "country": "DE",
        "postalCode": "60316",
        "city": "Frankfurt",
        "street": "Sandweg",
        "houseNumber": "61",
        "phoneNumbers": [
            {
                "value": "+49 69 580775",
                "type": "PHONE",
                "label": "Landline"
            }
        ],
        "emailAddresses": [
            {
                "value": "[email protected]",
                "recipient": "LU.XY Frankfurt 1"
            }
        ]
    },
    "locationType": "STORE",
    "tenantFacilityId": "1",
    "status": "ONLINE",
    "services": [
        {
            "type": "SHIP_FROM_STORE"
        },
        {
            "type": "PICKUP"
        }
    ],
    "pickingTimes": {
        "monday": [
            {
                "start": { "hour": 8, "minute": 0 },
                "end": { "hour": 17, "minute": 0 },
                "capacity": 20
            }
        ],
        "tuesday": [
            {
                "start": { "hour": 8, "minute": 0 },
                "end": { "hour": 17, "minute": 0 },
                "capacity": 20
            }
        ],
        "wednesday": [
            {
                "start": { "hour": 8, "minute": 0 },
                "end": { "hour": 17, "minute": 0 },
                "capacity": 20
            }
        ],
        "thursday": [
            {
                "start": { "hour": 8, "minute": 0 },
                "end": { "hour": 17, "minute": 0 },
                "capacity": 20
            }
        ],
        "friday": [
            {
                "start": { "hour": 8, "minute": 0 },
                "end": { "hour": 17, "minute": 0 },
                "capacity": 15
            }
        ],
        "saturday": [
            {
                "start": { "hour": 8, "minute": 0 },
                "end": { "hour": 17, "minute": 0 },
                "capacity": 10
            }
        ]
    }
}

The request payload includes the following properties:

  • name: The name used for the facility, which can be an internal identifier like "Frankfurt flagship store".

  • address: The physical location of the facility.

  • locationType: The type of location, which can be STORE, EXTERNAL, or WAREHOUSE. Warehouses do not offer Click&Collect services.

  • tenantFacilityId: The facility's ID in the tenant's external systems. This value is optional but must be unique if provided.

  • status: The facility's status after creation. ONLINE facilities can fulfill new orders. SUSPENDED facilities can complete their current workload but do not accept new orders. OFFLINE facilities cannot fulfill any orders.

  • services: A list of services the facility offers. For example, PICKUP enables Click&Collect, and SHIP_FROM_STORE enables direct shipping to customers.

  • pickingTimes: The time windows during which employees pick orders. These can differ from the facility's opening hours. A capacity can be defined for each time window to limit the number of orders processed within that timeframe.

The API responds with 201 CREATED, indicating the request was successful and including the created facility in its payload.

Example response
{
    "name": "LU.XY Fashion flagship store",
    "address": {
        "companyName": "lu.xy fashion GmbH",
        "country": "DE",
        "postalCode": "60316",
        "city": "Frankfurt",
        "street": "Sandweg",
        "houseNumber": "61",
        "phoneNumbers": [
            {
                "value": "+49 69 580775",
                "type": "PHONE",
                "label": "Landline"
            }
        ],
        "emailAddresses": [
            {
                "value": "[email protected]",
                "recipient": "LU.XY Frankfurt 1"
            }
        ]
    },
    "locationType": "STORE",
    "tenantFacilityId": "1",
    "status": "ONLINE",
    "services": [
        {
            "type": "SHIP_FROM_STORE"
        },
        {
            "type": "PICKUP"
        }
    ],
    "pickingTimes": {
        "monday": [
            {
                "start": {
                    "hour": 8,
                    "minute": 0
                },
                "end": {
                    "hour": 17,
                    "minute": 0
                },
                "capacity": 20
            }
        ],
        "tuesday": [
            {
                "start": {
                    "hour": 8,
                    "minute": 0
                },
                "end": {
                    "hour": 17,
                    "minute": 0
                },
                "capacity": 20
            }
        ],
        "wednesday": [
            {
                "start": {
                    "hour": 8,
                    "minute": 0
                },
                "end": {
                    "hour": 17,
                    "minute": 0
                },
                "capacity": 20
            }
        ],
        "thursday": [
            {
                "start": {
                    "hour": 8,
                    "minute": 0
                },
                "end": {
                    "hour": 17,
                    "minute": 0
                },
                "capacity": 20
            }
        ],
        "friday": [
            {
                "start": {
                    "hour": 8,
                    "minute": 0
                },
                "end": {
                    "hour": 17,
                    "minute": 0
                },
                "capacity": 15
            }
        ],
        "saturday": [
            {
                "start": {
                    "hour": 8,
                    "minute": 0
                },
                "end": {
                    "hour": 17,
                    "minute": 0
                },
                "capacity": 10
            }
        ]
    },
    "fulfillmentProcessBuffer": 240,
    "capacityEnabled": false,
    "created": "2023-11-14T15:26:43.165Z",
    "lastModified": "2023-11-14T15:26:43.165Z",
    "version": 1,
    "id": "d286e108-698b-4f6c-97b7-21f090f17e46"
}

The response includes additional properties not present in the request:

  • id: The unique ID for the facility in fulfillmenttools.

  • version: The entity's version in the database. This is used for locking mechanisms and is typically 1 upon creation.

  • fulfillmentProcessBuffer: The duration in minutes until an order is considered fully processed.

  • capacityEnabled: A boolean indicating whether configured capacity limits for picking times are enforced.

  • created: The timestamp indicating when the facility was created in fulfillmenttools.

  • lastModified: The timestamp indicating when the facility was last modified.

Adding warehouses

The same endpoint is used to add warehouses, but the payload differs. Warehouses in this example have picking times from 5:00 AM to 11:59 PM, Monday to Saturday, and higher capacities.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities
{
    "name": "LU.XY Warehouse Frankfurt",
    "address": {
        "companyName": "lu.xy logistics GmbH",
        "country": "DE",
        "postalCode": "63303",
        "city": "Dreieich",
        "street": "Landsteinerstraße",
        "houseNumber": "5",
        "phoneNumbers": [
            {
                "value": "+49 69 96358078",
                "type": "PHONE",
                "label": "Landline"
            }
        ],
        "emailAddresses": [
            {
                "value": "[email protected]",
                "recipient": "LU.XY Warehouse FRA"
            }
        ]
    },
    "locationType": "WAREHOUSE",
    "tenantFacilityId": "21",
    "status": "ONLINE",
    "services": [
        {
            "type": "SHIP_FROM_STORE"
        }
    ],
    "pickingTimes": {
        "monday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ],
        "tuesday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ],
        "wednesday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ],
        "thursday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ],
        "friday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ],
        "saturday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ]
    }
}

The API will again respond with a 201 CREATED status and the new warehouse entity.

Example response
{
    "name": "LU.XY Warehouse Frankfurt",
    "address": {
        "companyName": "lu.xy logistics GmbH",
        "country": "DE",
        "postalCode": "63303",
        "city": "Dreieich",
        "street": "Landsteinerstraße",
        "houseNumber": "5",
        "phoneNumbers": [
            {
                "value": "+49 69 96358078",
                "type": "PHONE",
                "label": "Landline"
            }
        ],
        "emailAddresses": [
            {
                "value": "[email protected]",
                "recipient": "LU.XY Warehouse FRA"
            }
        ]
    },
    "locationType": "WAREHOUSE",
    "tenantFacilityId": "21",
    "status": "ONLINE",
    "services": [
        {
            "type": "SHIP_FROM_STORE"
        }
    ],
    "pickingTimes": {
        "monday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ],
        "tuesday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ],
        "wednesday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ],
        "thursday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ],
        "friday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ],
        "saturday": [
            {
                "start": {
                    "hour": 5,
                    "minute": 0
                },
                "end": {
                    "hour": 23,
                    "minute": 59
                },
                "capacity": 100
            }
        ]
    },
    "fulfillmentProcessBuffer": 240,
    "capacityEnabled": false,
    "created": "2023-11-15T12:54:24.084Z",
    "lastModified": "2023-11-15T12:54:24.084Z",
    "version": 1,
    "id": "946f17d0-2d14-48f0-a912-d358f2c70e8f"
}

Disclaimer

The addresses were randomly picked by looking up the city on Google Maps and zooming into a random place in that city. If one of the addresses offends you in any way, please let us know, and we will change it immediately.

Last updated