Manage Location Types

This guide applies to standalone Curbside Delivery implementations. Order Management users integrating Curbside as an additional fulfillment type can use the standard Location API calls.

Location types should be defined before creating any fulfillment locations. There are no configurations or extensive actions done on types; they are simply labels that can be used to organize and filter fulfillment locations. For instance, “warehouse” and “storefront” are two types that may be used to identify whether a location is a warehouse location or a retail store. The Location Type API supports initializing types, retrieving information, and editing or deleting existing types.

Each of these POST, PUT, and GET calls are explained in this guide. Ask the Kibo team for additional examples and Postman samples if desired.

The Location Type Object

All calls made to the Location Type API have very simple request bodies, if any at all, because there are only two parameters that are used to define a type and none of the API calls require any additional information.

The template for this object, and thus the request bodies for creating and updating location type records, is:

{
  "code": "code",
  "name": "name",
}

Create Location Type

To create a new location type, a POST call should be made to the Location Types API.

The following example body shows how to define a location type that may be used to identify warehouses.

{
  "code": "warehouse",
  "name": "Warehouse Location",
}

If the creation is successful, a 200 OK response code will be returned by the API along with a response body repeating all of the configured location type information.

Get Specific Location Type Information

There are two methods to retrieve location type data – for a specific location type, or for all existing location types. To retrieve the data for a specific location type, the type’s code should be indicated in the endpoint while making a GET call.

For example, the following call would be made to retrieve the data of the location type set up in the above Create Location Type example:

https://integration.exampleURL.com/api/commerce/admin/locationtypes/warehouse/

The response would include the code and descriptive name of the location type, as well as audit information that indicates the date-time when the record was created and last updated, and by which user. This audit data is automatically set by the system, which is why it is never manually included in POST or PUT request bodies.

{
  "code": "warehouse",
  "name": "Warehouse Location",
  "auditInfo": {
        "updateDate": "2020-08-14T19:28:19Z",
        "createDate": "2020-08-14T19:28:19Z",
        "updateBy": "Example User",
        "createBy": "Example User"
  }
}

Get All Location Type Information

To retrieve the data of all location types that exist for the tenant, no code is appended to the endpoint of the GET call.

The response returns a list of all location type records that have been created. Each entry includes a code, name, and the system audit information. Note that there is no filtering, sorting, or pagination currently supported for these results.

This example includes the records for a tenant who has created warehouse, retail storefront, and drop shipper types.

{
  [
    {
      "code": "warehouse",
      "name": "Warehouse Location",
      "auditInfo": {
          "updateDate": "2020-08-14T19:28:19Z",
          "createDate": "2020-08-14T19:28:19Z",
          "updateBy": "Example User",
          "createBy": "Example User"
      }
  },
  {
      "code": "retail",
      "name": "Retail Storefront",
      "auditInfo": {
          "updateDate": "2020-08-14T19:28:19Z",
          "createDate": "2020-08-14T19:28:19Z",
          "updateBy": "Example User",
          "createBy": "Example User"
      }
  },
  {
      "code": "dropship",
      "name": "Drop Shipper",
      "auditInfo": {
          "updateDate": "2020-08-14T19:28:19Z",
          "createDate": "2020-08-14T19:28:19Z",
          "updateBy": "Example User",
          "createBy": "Example User"
      }
    }
  ]
}

Update Location Type Information

To edit a location type record after it has been created, make a PUT call to the Location Type API with the appropriate type code indicated in the endpoint. The request body for this call is exactly the same as the creation POST call, since location type data only consists of a code and name. This call would generally only need to be made if the type name must be edited.

For example, the following call would be made to edit the location type that was used as an example in the Create Location Type section of this guide.

>https://integration.exampleURL.com/api/commerce/admin/locations/warehouse/

The request body changes the location type’s name.

{
  "code": "warehouse",
  "name": "Fulfillment Warehouse",
}

If successful, a 200 OK response code will be received along with the updated location type data, such as what would be returned from a GET call.

Delete Location Type

If a location type record needs to be deleted, then the following API call can be made to remove the record.

There is neither a request body nor a response body that is required – if the deletion was successful, then a 200 OK response code will be returned.