Skip to main content

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

LocationCategoriesPayload​

Result of the locationCategories query.

FieldTypeDescription
categories[LocationCategory!]!The predefined location categories available for classifying locations in the hierarchy.
LocationCategory​

A node in the location category hierarchy.

FieldTypeDescription
childCategoryIds[String!]Identifiers of categories nested directly beneath this one.
idStringUnique identifier of the location category.
parentCategoryIdStringIdentifier 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​

LocationRolesPayload

LocationRole​

A role classifying how a location is used (e.g. staging, shipping, storage).

FieldTypeDescription
descriptionStringFree-text description of the role.
idStringUnique identifier of the location role.
nameStringDisplay name of the role.
LocationRolesPayload​

Result of the locationRoles query.

FieldTypeDescription
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.

FieldTypeDescription
filterStringFilter expression applied to location properties.
nextTokenStringOpaque pagination token from a previous response to fetch the next page.

Returns​

LocationsPayload

LocationsPayload​

Result of the locations query.

FieldTypeDescription
locations[LocationV2!]Locations matching the query, each with its category, role, and assigned customer.
nextTokenStringOpaque 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.

FieldTypeDescription
categoryIdString!Identifier of the predefined category that determines the location's level in the hierarchy.
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
customerIdStringIdentifier of the customer assigned to the location, if any.
descriptionStringFree-text description of the location.
idString!Unique identifier of the location, used for all future transactions.
nameStringDisplay name of the location.
parentLocationIdStringIdentifier of the parent location in the hierarchy, if any.
roleIdStringIdentifier of the role to assign to the location, if any.
CreateLocationsInput​

Input for the createLocations mutation.

FieldTypeDescription
locations[CreateLocationInput!]!Locations to create.

Returns​

CreateLocationsPayload

CreateLocationsPayload​

Result of the createLocations mutation.

FieldTypeDescription
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.

FieldTypeDescription
locationIds[String!]!Identifiers of the locations to delete.

Returns​

DeleteLocationsPayload

DeleteLocationsPayload​

Result of the deleteLocations mutation.

FieldTypeDescription
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.

FieldTypeDescription
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
customerIdStringIdentifier of the customer this location belongs to.
descriptionStringFree-text description of the location.
idStringUnique identifier of the location.
nameStringDisplay name of the location.
parentLocationIdStringIdentifier of the parent location, establishing the hierarchy.
roleIdStringIdentifier of the role to assign to the location.
UpdateLocationInput​

A single location update as part of the updateLocations mutation.

FieldTypeDescription
idString!Unique identifier of the location to update.
updatesLocationUpdates!Fields to update on the location.
UpdateLocationsInput​

Input for the updateLocations mutation.

FieldTypeDescription
locations[UpdateLocationInput!]!Locations to update.

Returns​

UpdateLocationsPayload

UpdateLocationsPayload​

Result of the updateLocations mutation.

FieldTypeDescription
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.

FieldTypeDescription
categoryIdStringIdentifier of the location category this location is classified under.
childLocationIds[String!]Identifiers of locations nested directly beneath this one.
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
customerIdStringIdentifier of the customer this location belongs to, if any.
descriptionStringFree-text description of the location.
idStringUnique identifier of the location.
nameStringDisplay name of the location.
parentLocationIdStringIdentifier of the parent location in the hierarchy, if any.
roleIdStringIdentifier of the location role describing how this location is used.