Locations

Location Model

Properties

  • Name
    id
    Type
    string
    Description

    The unique identifier for the location.

  • Name
    name
    Type
    string
    Restrictions
    Description

    The name of the location. Only used for internal identification.

  • Name
    tags
    Type
    array,null
    Restrictions
    Description

    An array of tags attached to the location. Allows for filtering the location depending on whether certain criteria are met.

  • Name
    address
    Type
    [Address](#schemaaddress)
    Restrictions
    Description
  • Name
    marketplaces
    Type
    object
    Restrictions
    Description

    An object containing the mappings for the given location to its counterpart on an external marketplace. All external location IDs should be passed as strings, regardless of original type.

  • Name
    » ^[a-zA-Z0-9_]{0,50}$
    Type
    array
    Restrictions
    Description
  • Name
    » **additionalProperties**
    Type
    string
    Restrictions
    Description
{
  "id": "loc_2KHgyqnlg9pS4404i69Lr0hbcKI",
  "name": "DC-EMEA-SOM1",
  "tags": [],
  "address": {
    "address": {
      "line_1": "Unit 15A",
      "line_2": "Brundish Business Park",
      "city": "Somerhull",
      "post_code": "SH9 7FG",
      "country_code": "GB"
    },
    "contact": {
      "name": "John K.",
      "email_address": "[email protected]",
      "phone_number": "+447192759164"
    }
  },
  "marketplaces": {
    "shopify": [
      "gid://shopify/Location/37128937918",
      "gid://shopify/Location/352389427886"
    ]
  },
  "created_at": "2023-01-13T19:12:59Z",
  "updated_at": "2023-01-13T20:00:13Z"
}

Location Configuration Model

Properties

  • Name
    id
    Type
    string
    Description

    The unique ID of the location configuration.

  • Name
    name
    Type
    string
    Restrictions
    Description

    A display name for the location configuration.

  • Name
    locations
    Type
    object
    Restrictions
    Description
  • Name
    » origin
    Type
    [Location](#schemalocation)
    Restrictions
    Description

    The location from which shipments will originate.

  • Name
    » return
    Type
    [Location](#schemalocation)
    Restrictions
    Description

    The location where shipments that fail to be delivered will be returned to.

  • Name
    created_at
    Type
    string
    Restrictions
    Description
  • Name
    updated_at
    Type
    string
    Restrictions
    Description
{
  "id": "lc_2Kp4inYBJgHVzc3uUwClc9btTEB",
  "name": "Retail Somerhull (2C/4B)",
  "locations": {
    "origin": {
      "id": "loc_2KHgyqnlg9pS4404i69Lr0hbcKI",
      "name": "DC-EMEA-SOM1",
      "tags": [],
      "address": {
        "address": {
          "line_1": "Unit 15A",
          "line_2": "Brundish Business Park",
          "city": "Somerhull",
          "post_code": "SH9 7FG",
          "country_code": "GB"
        },
        "contact": {
          "name": "John K.",
          "email_address": "[email protected]",
          "phone_number": "+447192759164"
        }
      },
      "marketplaces": {
        "shopify": [
          "gid://shopify/Location/37128937918",
          "gid://shopify/Location/352389427886"
        ]
      },
      "created_at": "2023-01-13T19:12:59Z",
      "updated_at": "2023-01-13T20:00:13Z"
    },
    "return": {
      "id": "loc_2KHgyqnlg9pS4404i69Lr0hbcKI",
      "name": "DC-EMEA-SOM1",
      "tags": [],
      "address": {
        "address": {
          "line_1": "Unit 15A",
          "line_2": "Brundish Business Park",
          "city": "Somerhull",
          "post_code": "SH9 7FG",
          "country_code": "GB"
        },
        "contact": {
          "name": "John K.",
          "email_address": "[email protected]",
          "phone_number": "+447192759164"
        }
      },
      "marketplaces": {
        "shopify": [
          "gid://shopify/Location/37128937918",
          "gid://shopify/Location/352389427886"
        ]
      },
      "created_at": "2023-01-13T19:12:59Z",
      "updated_at": "2023-01-13T20:00:13Z"
    }
  },
  "created_at": "string",
  "updated_at": "string"
}

Coordinates Model

Properties

  • Name
    Coordinates
    Type
    object,null
    Restrictions
    Description

    A set of latitude/longitude coordinates, which may optionally contain a confidence score from 0.0 - 1.0 if the coordinates are the result of geocoding.

  • Name
    latitude
    Type
    number(double)
    Restrictions
    Description
  • Name
    longitude
    Type
    number(double)
    Restrictions
    Description
  • Name
    confidence
    Type
    number,null(float)
    Restrictions
    Description

    A confidence score associated with the cordinates, indicating how accurately they represent the address.

    For manually set coordinates, set the confidence score to 1 to indicate that the location has been manually specified/verified.

{
  "latitude": 51.7864239,
  "longitude": -0.9725901,
  "confidence": 0.9201
}
GET/locations

Get Locations

Retrieve a list of locations for an organisation.

This endpoint is the primary means for retrieving locations belonging to an organisation. A location encapsulates a physical place that is present in regular business activities, such as a warehouse or a retail location.

When sending out shipments, shipments are linked to the location that sends them. It is possible to specify different locations for the different requirements for a shipment, as in the following example:

  • Shipments are to be sent from the main warehouse in Berlin (BER-3).
  • In the event of a failed delivery, returns are processed at a different warehouse in Amsterdam (AMS-1).
  • To achieve this, one would Create a Location Configuration, specifying the ID for the BER-3 location in the origin location field, and the AMS-1 location in the return location field, and provide a name for the configuration, such as BER/AMS Retail.
  • The newly created location configuration can then be used during fulfilment to auto-fill the correct details for the shipment origin and return fields.

Location Configurations are intended to be setup once and reused multiple times to avoid the need for manual entry/selection of shipment details that are unlikely to change.

As with other resources, this endpoint returns paginated results. The details of how pagination works can be found in the pagination article.

Request

GET
/locations
curl --request GET \
--url https://api.envoy.one/locations \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "locations": [
    {
      "id": "loc_2KHgyqnlg9pS4404i69Lr0hbcKI",
      "name": "DC-EMEA-SOM1",
      "tags": [],
      "address": {
        "address": {
          "line_1": "Unit 15A",
          "line_2": "Brundish Business Park",
          "city": "Somerhull",
          "post_code": "SH9 7FG",
          "country_code": "GB"
        },
        "contact": {
          "name": "John K.",
          "email_address": "[email protected]",
          "phone_number": "+447192759164"
        }
      },
      "created_at": "2023-01-13T19:12:59Z",
      "updated_at": "2023-01-13T20:00:13Z"
    }
  ],
  "next_cursor": "WyJsb2NfMk5EVk1ZTTlRNWl0RVNLT0lBZkp2eDJGSDhyIiwiMjAyMy0wMy0xOVQwNDowMzoxMS44NzYxMjFaIl0=",
  "previous_cursor": "WyJsb2NfMk44bk1qZTZHT3RqYzdjZTlBamtRSG1rR0owIiwiMjAyMy0wMy0xN1QxMjowMjoxMC4zNDk4M1oiXQ==",
  "limit": 20
}

undefined

POST/locations

Create Location

Create a location with the provided information.

Request

POST
/locations
curl --request POST \
--url https://api.envoy.one/locations \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"DC-EMEA-SOM1","address":{"address":{"line_1":"Unit 15A","line_2":"Brundish Business Park","city":"Somerhull","post_code":"SH9 7FG","country_code":"GB"},"contact":{"name":"John K.","email_address":"[email protected]","phone_number":"+447192759164"}}}'

Response

{
  "id": "loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C",
  "name": "DC-EMEA-SOM3",
  "tags": [
    "accepts_returns"
  ],
  "address": {
    "address": {
      "line_1": "Unit 2B",
      "line_2": "Brundish Business Park",
      "city": "Somerhull",
      "post_code": "SH9 7FG",
      "country_code": "GB"
    },
    "contact": {
      "name": "John K.",
      "email_address": "[email protected]",
      "phone_number": "+447192759164"
    }
  },
  "created_at": "2023-01-24T02:44:46Z",
  "updated_at": "2023-01-24T02:44:46Z"
}

undefined

GET/locations/{location_id}

Get Location

Retrieve a location by it's ID.

Path Parameters

  • Name
    location_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location.

Request

GET
/locations/{location_id}
curl --request GET \
--url https://api.envoy.one/locations/loc_2KmdpbdotbekAsGL50uAfSxe4Ma \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "id": "loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C",
  "name": "DC-EMEA-SOM1",
  "tags": [],
  "address": {
    "address": {
      "line_1": "Unit 15A",
      "line_2": "Brundish Business Park",
      "city": "Somerhull",
      "post_code": "SH9 7FG",
      "country_code": "GB"
    },
    "contact": {
      "name": "John K.",
      "email_address": "[email protected]",
      "phone_number": "+447192759164"
    }
  },
  "created_at": "2023-01-24T02:44:46Z",
  "updated_at": "2023-01-25T15:03:25Z"
}

undefined

PATCH/locations/{location_id}

Update Location

Update a location by it's ID.

Depending on which fields are updated, it may be necessary for our servers to create a new address record on the courier's systems. If this is necessary, it's possible that some unexpected behaviour may occur when it comes to manifesting any pending shipments linked to the location. These may include, depending on the carrier:

  • Multiple manifests being created, with the pending shipments being split across the manifests.
  • Shipments missing from the manifest.

In the event that such unexpected behaviour occurs, shipments will usually be automatically manifested automatically by the courier during their end of day processing.

Changes to the location will not affect the validity of any existing shipments in any way. The only caveats are those as described above regarding the manifesting behaviour.

To minimise the chances of such behaviour being encountered, we suggest making any changes to the location outside of the times when you are fulfilling orders.

Path Parameters

  • Name
    location_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location.

Request

PATCH
/locations/{location_id}
curl --request PATCH \
--url https://api.envoy.one/locations/loc_2KmdpbdotbekAsGL50uAfSxe4Ma \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"DC-EMEA-SOM1","address":{"address":{"line_1":"Unit 15A"}}}'

Response

{
  "id": "loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C",
  "name": "DC-EMEA-SOM1",
  "tags": [],
  "address": {
    "address": {
      "line_1": "Unit 15A",
      "line_2": "Brundish Business Park",
      "city": "Somerhull",
      "post_code": "SH9 7FG",
      "country_code": "GB"
    },
    "contact": {
      "name": "John K.",
      "email_address": "[email protected]",
      "phone_number": "+447192759164"
    }
  },
  "created_at": "2023-01-24T02:44:46Z",
  "updated_at": "2023-01-25T15:03:25Z"
}

undefined

DELETE/locations/{location_id}

Delete Location

Delete a location by it's ID.

As a pre-requisite to deleting a location, the location cannot be in use by any Location Configuration. If the location is currently being used, first Update the Location Configuration with a different location, then once all configurations have been reassigned, the location can be deleted. Attempting to delete a location whilst it is being used by a configuration will result in a 409 Conflict error being returned.

Deleting a location will not affect any existing shipments that have been created - each shipment stores the details of the location when it is originally created.

Path Parameters

  • Name
    location_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location.

Request

DELETE
/locations/{location_id}
curl --request DELETE \
--url https://api.envoy.one/locations/loc_2KmdpbdotbekAsGL50uAfSxe4Ma \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined

GET/location_configurations

Get Location Configurations

Retrieve a list of location configurations for an organisation.

Location Configurations are part of the fulfilment process, and are used to create predefined configurations that are commonly used when shipping orders, typically encalsulating an origin location and a return location, which is used in the event that a shipment cannot be delivered. In most cases, both the origin and return locations will be the same.

When sending out shipments, shipments are linked to the location that sends them. It is possible to specify different locations for the different requirements for a shipment, as in the following example:

  • Shipments are to be sent from the main warehouse in Berlin (BER-3).
  • In the event of a failed delivery, returns are processed at a different warehouse in Amsterdam (AMS-1).
  • To achieve this, one would Create a Location Configuration, specifying the ID for the BER-3 location in the origin location field, and the AMS-1 location in the return location field, and provide a name for the configuration, such as BER/AMS Retail.
  • The newly created location configuration can then be used during fulfilment to auto-fill the correct details for the shipment origin and return fields.

Location Configurations are intended to be setup once and reused multiple times to avoid the need for manual entry/selection of shipment details that are unlikely to change.

As with other resources, this endpoint returns paginated results. The details of how pagination works can be found in the pagination article.

Request

GET
/location_configurations
curl --request GET \
--url https://api.envoy.one/location_configurations \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "location_configurations": [
    {
      "id": "lc_2Kp4inYBJgHVzc3uUwClc9btTEB",
      "name": "Retail Somerhull (2C/4B)",
      "locations": {
        "origin": {
          "id": "loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C",
          "name": "DC-EMEA-SOM1",
          "tags": [],
          "created_at": "2023-01-24T02:44:46Z",
          "updated_at": "2023-01-24T18:32:31Z"
        },
        "return": {
          "id": "loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C",
          "name": "DC-EMEA-SOM1",
          "tags": [],
          "created_at": "2023-01-24T02:44:46Z",
          "updated_at": "2023-01-24T18:32:31Z"
        }
      },
      "created_at": "2023-01-25T14:51:59Z",
      "updated_at": "2023-01-25T14:51:59Z"
    }
  ],
  "next_cursor": "WyJsb2NfMk5EVk1ZTTlRNWl0RVNLT0lBZkp2eDJGSDhyIiwiMjAyMy0wMy0xOVQwNDowMzoxMS44NzYxMjFaIl0=",
  "previous_cursor": "WyJsb2NfMk44bk1qZTZHT3RqYzdjZTlBamtRSG1rR0owIiwiMjAyMy0wMy0xN1QxMjowMjoxMC4zNDk4M1oiXQ==",
  "limit": 20
}

undefined

POST/location_configurations

Create Location Configuration

Create a location configuration with the provided information.

Request

POST
/location_configurations
curl --request POST \
--url https://api.envoy.one/location_configurations \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"Retail Somerhull (2C/4B)","locations":{"origin":{"id":"loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C"},"return":{"id":"loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C"}}}'

Response

{
  "id": "loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C",
  "name": "DC-EMEA-SOM3",
  "tags": [
    "accepts_returns"
  ],
  "address": {
    "address": {
      "line_1": "Unit 2B",
      "line_2": "Brundish Business Park",
      "city": "Somerhull",
      "post_code": "SH9 7FG",
      "country_code": "GB"
    },
    "contact": {
      "name": "John K.",
      "email_address": "[email protected]",
      "phone_number": "+447192759164"
    }
  },
  "created_at": "2023-01-24T02:44:46Z",
  "updated_at": "2023-01-24T02:44:46Z"
}

undefined

GET/location_configurations/{location_configuration_id}

Get Location Configuration

Retrieve a location configuration by it's ID.

Path Parameters

  • Name
    location_configuration_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location configuration.

Request

GET
/location_configurations/{location_configuration_id}
curl --request GET \
--url https://api.envoy.one/location_configurations/lc_2KmtYWmAGqpU8f0aJrFfUNRQ5KX \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "id": "lc_2Kp4inYBJgHVzc3uUwClc9btTEB",
  "name": "Retail Somerhull (2C/4B)",
  "locations": {
    "origin": {
      "id": "loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C",
      "name": "DC-EMEA-SOM1",
      "tags": [],
      "address": {
        "address": {
          "line_1": "Unit 15A",
          "line_2": "Brundish Business Park",
          "city": "Somerhull",
          "post_code": "SH9 7FG",
          "country_code": "GB"
        },
        "contact": {
          "name": "John K.",
          "email_address": "[email protected]",
          "phone_number": "+447192759164"
        }
      },
      "created_at": "2023-01-24T02:44:46Z",
      "updated_at": "2023-01-25T15:03:25Z"
    },
    "return": {
      "id": "loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C",
      "name": "DC-EMEA-SOM1",
      "tags": [],
      "address": {
        "address": {
          "line_1": "Unit 15A",
          "line_2": "Brundish Business Park",
          "city": "Somerhull",
          "post_code": "SH9 7FG",
          "country_code": "GB"
        },
        "contact": {
          "name": "John K.",
          "email_address": "[email protected]",
          "phone_number": "+447192759164"
        }
      },
      "created_at": "2023-01-24T02:44:46Z",
      "updated_at": "2023-01-25T15:03:25Z"
    }
  },
  "created_at": "2023-01-25T14:51:59Z",
  "updated_at": "2023-01-25T14:51:59Z"
}

undefined

PATCH/location_configurations/{location_configuration_id}

Update Location Configuration

Update a location configuration by it's ID.

Path Parameters

  • Name
    location_configuration_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location configuration.

Request

PATCH
/location_configurations/{location_configuration_id}
curl --request PATCH \
--url https://api.envoy.one/location_configurations/lc_2KmtYWmAGqpU8f0aJrFfUNRQ5KX \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"Retail Somerhull (6C/2B)","locations":{"origin":{"id":"loc_2KHgyqnlg9pS4404i69Lr0hbcKI"}}}'

Response

{
  "id": "lc_2Kp4inYBJgHVzc3uUwClc9btTEB",
  "name": "Retail Somerhull (6C/2B)",
  "locations": {
    "origin": {
      "id": "loc_2KHgyqnlg9pS4404i69Lr0hbcKI",
      "name": "DC-EMEA-SOM5",
      "tags": [],
      "address": {
        "address": {
          "line_1": "Unit 15A",
          "line_2": "Brundish Business Park",
          "city": "Somerhull",
          "post_code": "SH9 7FG",
          "country_code": "GB"
        },
        "contact": {
          "name": "John K.",
          "email_address": "[email protected]",
          "phone_number": "+447192759164"
        }
      },
      "created_at": "2023-01-13T19:12:59Z",
      "updated_at": "2023-01-13T20:00:13Z"
    },
    "return": {
      "id": "loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C",
      "name": "DC-EMEA-SOM1",
      "tags": [],
      "address": {
        "address": {
          "line_1": "Unit 15A",
          "line_2": "Brundish Business Park",
          "city": "Somerhull",
          "post_code": "SH9 7FG",
          "country_code": "GB"
        },
        "contact": {
          "name": "John K.",
          "email_address": "[email protected]",
          "phone_number": "+447192759164"
        }
      },
      "created_at": "2023-01-24T02:44:46Z",
      "updated_at": "2023-01-25T15:03:25Z"
    }
  },
  "created_at": "2023-01-25T14:51:59Z",
  "updated_at": "2023-01-25T17:09:24Z"
}

undefined

DELETE/location_configurations/{location_configuration_id}

Delete Location Configuration

Delete a location configuration by it's ID.

Deleting a location configuration will not affect any existing shipments that have been created that utilise the configuration in question - each shipment stores the details of the location when it is created.

Path Parameters

  • Name
    location_configuration_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location configuration.

Request

DELETE
/location_configurations/{location_configuration_id}
curl --request DELETE \
--url https://api.envoy.one/location_configurations/lc_2KmtYWmAGqpU8f0aJrFfUNRQ5KX \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined