Locations API
Authentication: every request needs an
IdToken— see Authentication. Error shapes: Errors.
Endpoint: POST https://api.xemelgo.com/graphql
Queries
locationCategories
List the location categories available in the tenant's hierarchy.
query LocationCategories {
locationCategories {
categories {
childCategoryIds
id
parentCategoryId
}
}
}
Example variables
{}
Example response
{
"data": {
"locationCategories": {
"categories": [
{
"childCategoryIds": [
"example"
],
"id": "locationcategory-001",
"parentCategoryId": "parentcategory-001"
}
]
}
}
}
Arguments
This operation takes no arguments.
Returns
LocationCategoriesPayload
Result of the locationCategories query.
| Field | Type | Description |
|---|---|---|
categories | [LocationCategory!]! | The predefined location categories available for classifying locations in the hierarchy. |
LocationCategory
A node in the location category hierarchy.
| Field | Type | Description |
|---|---|---|
childCategoryIds | [String!] | Identifiers of categories nested directly beneath this one. |
id | String | Unique identifier of the location category. |
parentCategoryId | String | Identifier of the parent category, if any. |
locationRoles
List the location roles that can be assigned to a location.
query LocationRoles {
locationRoles {
roles {
description
id
name
}
}
}
Example variables
{}
Example response
{
"data": {
"locationRoles": {
"roles": [
{
"description": "Electric counterbalance forklift",
"id": "locationrole-001",
"name": "Forklift 7"
}
]
}
}
}
Arguments
This operation takes no arguments.
Returns
LocationRole
A role classifying how a location is used (e.g. staging, shipping, storage).
| Field | Type | Description |
|---|---|---|
description | String | Free-text description of the role. |
id | String | Unique identifier of the location role. |
name | String | Display name of the role. |
LocationRolesPayload
Result of the locationRoles query.
| Field | Type | Description |
|---|---|---|
roles | [LocationRole!]! | The predefined location roles that can be assigned to a location. |
locations
List locations with their category, role, and assigned customer.
query Locations($input: LocationsInput) {
locations(input: $input) {
nextToken
locations {
categoryId
childLocationIds
customerId
customProperties
description
id
name
parentLocationId
roleId
}
}
}
Example variables
{
"input": {
"filter": "name:\"Forklift*\"",
"nextToken": "eyJpZCI6IjEwMjQifQ=="
}
}
Example response
{
"data": {
"locations": {
"nextToken": "eyJpZCI6IjEwMjQifQ==",
"locations": [
{
"categoryId": "category-001",
"childLocationIds": [
"example"
],
"customerId": "customer-001",
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"id": "location-001",
"name": "Forklift 7",
"parentLocationId": "parentlocation-001",
"roleId": "role-001"
}
]
}
}
}
Arguments
input · LocationsInput
LocationsInput
Input for filtering and paging the locations query.
| Field | Type | Description |
|---|---|---|
filter | String | Filter expression applied to location properties. |
nextToken | String | Opaque pagination token from a previous response to fetch the next page. |
Returns
LocationsPayload
Result of the locations query.
| Field | Type | Description |
|---|---|---|
locations | [LocationV2!] | Locations matching the query, each with its category, role, and assigned customer. |
nextToken | String | Opaque pagination token to fetch the next page, if more results exist. |
Mutations
createLocations
Create one or more locations and build the location hierarchy.
mutation CreateLocations($input: CreateLocationsInput!) {
createLocations(input: $input) {
locationIds
}
}
Example variables
{
"input": {
"locations": [
{
"categoryId": "category-001",
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"customerId": "customer-001",
"description": "Electric counterbalance forklift",
"id": "createlocation-001",
"name": "Forklift 7",
"parentLocationId": "parentlocation-001",
"roleId": "role-001"
}
]
}
}
Example response
{
"data": {
"createLocations": {
"locationIds": [
"example"
]
}
}
}
Arguments
input · CreateLocationsInput!
CreateLocationInput
A single location to create as part of the createLocations mutation.
| Field | Type | Description |
|---|---|---|
categoryId | String! | Identifier of the predefined category that determines the location's level in the hierarchy. |
customProperties | AWSJSON | Additional custom properties, serialized as a JSON string. |
customerId | String | Identifier of the customer assigned to the location, if any. |
description | String | Free-text description of the location. |
id | String! | Unique identifier of the location, used for all future transactions. |
name | String | Display name of the location. |
parentLocationId | String | Identifier of the parent location in the hierarchy, if any. |
roleId | String | Identifier of the role to assign to the location, if any. |
CreateLocationsInput
Input for the createLocations mutation.
| Field | Type | Description |
|---|---|---|
locations | [CreateLocationInput!]! | Locations to create. |
Returns
CreateLocationsPayload
Result of the createLocations mutation.
| Field | Type | Description |
|---|---|---|
locationIds | [String!]! | Identifiers of the created locations. |
deleteLocations
Permanently delete one or more locations.
mutation DeleteLocations($input: DeleteLocationsInput!) {
deleteLocations(input: $input) {
locationIds
}
}
Example variables
{
"input": {
"locationIds": [
"example"
]
}
}
Example response
{
"data": {
"deleteLocations": {
"locationIds": [
"example"
]
}
}
}
Arguments
input · DeleteLocationsInput!
DeleteLocationsInput
Input for the deleteLocations mutation.
| Field | Type | Description |
|---|---|---|
locationIds | [String!]! | Identifiers of the locations to delete. |
Returns
DeleteLocationsPayload
Result of the deleteLocations mutation.
| Field | Type | Description |
|---|---|---|
locationIds | [String!]! | Identifiers of the deleted locations. |
updateLocations
Update one or more existing locations with new properties.
mutation UpdateLocations($input: UpdateLocationsInput!) {
updateLocations(input: $input) {
locations {
categoryId
childLocationIds
customerId
customProperties
description
id
name
parentLocationId
roleId
}
}
}
Example variables
{
"input": {
"locations": [
{
"id": "updatelocation-001",
"updates": {
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"customerId": "customer-001",
"description": "Electric counterbalance forklift",
"id": "location-001",
"name": "Forklift 7",
"parentLocationId": "parentlocation-001",
"roleId": "role-001"
}
}
]
}
}
Example response
{
"data": {
"updateLocations": {
"locations": [
{
"categoryId": "category-001",
"childLocationIds": [
"example"
],
"customerId": "customer-001",
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"id": "location-001",
"name": "Forklift 7",
"parentLocationId": "parentlocation-001",
"roleId": "role-001"
}
]
}
}
}
Arguments
input · UpdateLocationsInput!
LocationUpdates
Fields to update on an existing location.
| Field | Type | Description |
|---|---|---|
customProperties | AWSJSON | Additional custom properties, serialized as a JSON string. |
customerId | String | Identifier of the customer this location belongs to. |
description | String | Free-text description of the location. |
id | String | Unique identifier of the location. |
name | String | Display name of the location. |
parentLocationId | String | Identifier of the parent location, establishing the hierarchy. |
roleId | String | Identifier of the role to assign to the location. |
UpdateLocationInput
A single location update as part of the updateLocations mutation.
| Field | Type | Description |
|---|---|---|
id | String! | Unique identifier of the location to update. |
updates | LocationUpdates! | Fields to update on the location. |
UpdateLocationsInput
Input for the updateLocations mutation.
| Field | Type | Description |
|---|---|---|
locations | [UpdateLocationInput!]! | Locations to update. |
Returns
UpdateLocationsPayload
Result of the updateLocations mutation.
| Field | Type | Description |
|---|---|---|
locations | [LocationV2!]! | Updated locations with their new properties. |
Shared types
Entity types used across multiple operations on this page. Type names throughout link here.
LocationV2
A location in the tenant's location hierarchy.
| Field | Type | Description |
|---|---|---|
categoryId | String | Identifier of the location category this location is classified under. |
childLocationIds | [String!] | Identifiers of locations nested directly beneath this one. |
customProperties | AWSJSON | Additional custom properties, serialized as a JSON string. |
customerId | String | Identifier of the customer this location belongs to, if any. |
description | String | Free-text description of the location. |
id | String | Unique identifier of the location. |
name | String | Display name of the location. |
parentLocationId | String | Identifier of the parent location in the hierarchy, if any. |
roleId | String | Identifier of the location role describing how this location is used. |