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 to1
to indicate that the location has been manually specified/verified.
{
"latitude": 51.7864239,
"longitude": -0.9725901,
"confidence": 0.9201
}
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 thereturn
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
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
Create Location
Create a location with the provided information.
Request
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 Location
Retrieve a location by it's ID.
Path Parameters
- Name
location_id
- Type
- string
- Restrictions
- Description
The unique ID for a location.
Request
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
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
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 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
curl --request DELETE \
--url https://api.envoy.one/locations/loc_2KmdpbdotbekAsGL50uAfSxe4Ma \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
undefined
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 thereturn
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
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
Create Location Configuration
Create a location configuration with the provided information.
Request
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 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
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
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
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 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
curl --request DELETE \
--url https://api.envoy.one/location_configurations/lc_2KmtYWmAGqpU8f0aJrFfUNRQ5KX \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
undefined