Skip to main content

Packages API

Authentication: every request needs an IdToken — see Authentication. Error shapes: Errors.

Endpoint: POST https://api.xemelgo.com/graphql

Queries​

packageRoute​

Returns the location route history for a package.

query PackageRoute($input: PackageRouteInput) {
packageRoute(input: $input) {
nextToken
route {
customProperties
duration
endDate
startDate
state
location {
id
name
}
}
}
}
Example variables
{
"input": {
"endDate": 1719792000000,
"id": "packageroute-001",
"nextToken": "eyJpZCI6IjEwMjQifQ==",
"startDate": 1719792000000
}
}
Example response
{
"data": {
"packageRoute": {
"nextToken": "eyJpZCI6IjEwMjQifQ==",
"route": [
{
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"duration": 1719792000000,
"endDate": 1719792000000,
"startDate": 1719792000000,
"state": "ACTIVE",
"location": {
"id": "location-001",
"name": "Forklift 7"
}
}
]
}
}
}

Arguments​

input · PackageRouteInput

PackageRouteInput​

Input for the packageRoute query.

FieldTypeDescription
endDateAWSTimestampEpoch-millisecond timestamp marking the end of the route window.
idString!Unique identifier of the package whose route is requested.
nextTokenStringPagination token for fetching the next page of results.
startDateAWSTimestampEpoch-millisecond timestamp marking the start of the route window.

Returns​

PackageRoutePayload

PackageRoute​

A single stop in a package's location route history.

FieldTypeDescription
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
durationAWSTimestampDuration the package spent at this stop.
endDateAWSTimestampEpoch-millisecond timestamp when the package left this stop.
locationLocationV2Location of this route stop.
startDateAWSTimestampEpoch-millisecond timestamp when the package entered this stop.
stateStringState of the package at this route stop.
PackageRoutePayload​

Result of the packageRoute query.

FieldTypeDescription
nextTokenStringPagination token for fetching the next page of results.
route[PackageRoute!]Ordered list of route stops for the package.

Mutations​

createPackages​

Creates one or more packages. If creation succeeds but complete package details are unavailable, the response includes the created packages' id and uuid, along with an error. Do not retry creation for those packages.

mutation CreatePackages($input: CreatePackagesInput!) {
createPackages(input: $input) {
packages {
comments
containerId
creationDate
customProperties
description
id
lastDetectionDate
lastUpdatedDate
name
state
transferOrderId
transferStatus
uuid
lastDetectedAtLocation {
id
name
}
location {
id
name
}
trackers {
serial
}
}
}
}
Example variables
{
"input": {
"packages": [
{
"comments": "Inspected and approved",
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"id": "package-001",
"locationId": "location-001",
"name": "Forklift 7",
"trackers": [
{
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"encodingFormat": "example",
"reuseTrackerSerial": false,
"serial": "E28011700000020ABC12345"
}
]
}
]
}
}
Example response
{
"data": {
"createPackages": {
"packages": [
{
"comments": "Inspected and approved",
"containerId": "container-001",
"creationDate": 1719792000000,
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"id": "package-001",
"lastDetectionDate": 1719792000000,
"lastUpdatedDate": 1719792000000,
"name": "Forklift 7",
"state": "ACTIVE",
"transferOrderId": "transferorder-001",
"transferStatus": "example",
"uuid": "uu-001",
"lastDetectedAtLocation": {
"id": "location-001",
"name": "Forklift 7"
},
"location": {
"id": "location-001",
"name": "Forklift 7"
},
"trackers": [
{
"serial": "E28011700000020ABC12345"
}
]
}
]
}
}
}

Arguments​

input · CreatePackagesInput!

CreatePackagesInput​

Input for the createPackages mutation.

FieldTypeDescription
packages[PackageInput!]!Packages to create.
PackageInput​

A single package to create.

FieldTypeDescription
commentsStringAny comments or remarks recorded for the package.
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
descriptionStringFree-text description of the package.
idString!Serial or unique identifier for the package.
locationIdStringIdentifier of the location the package is at.
nameStringDisplay name of the package.
trackers[TrackerInput!]Trackers to attach to the package.

Returns​

CreatePackagesPayload

CreatePackagesPayload​

Result of the createPackages mutation.

FieldTypeDescription
packages[Package!]The created packages.

deletePackages​

Deletes one or more packages and returns their identifiers.

mutation DeletePackages($input: DeletePackagesInput!) {
deletePackages(input: $input) {
packageIds
}
}
Example variables
{
"input": {
"packageIds": [
"example"
]
}
}
Example response
{
"data": {
"deletePackages": {
"packageIds": [
"example"
]
}
}
}

Arguments​

input · DeletePackagesInput!

DeletePackagesInput​

Input for the deletePackages mutation.

FieldTypeDescription
packageIds[String!]!Identifiers of the packages to delete.

Returns​

DeletePackagesPayload

DeletePackagesPayload​

Result of the deletePackages mutation.

FieldTypeDescription
packageIds[String!]!Identifiers of the deleted packages.

updatePackages​

Updates one or more packages and returns the updated records.

mutation UpdatePackages($input: UpdatePackagesInput!) {
updatePackages(input: $input) {
packages {
comments
containerId
creationDate
customProperties
description
id
lastDetectionDate
lastUpdatedDate
name
state
transferOrderId
transferStatus
uuid
lastDetectedAtLocation {
id
name
}
location {
id
name
}
trackers {
serial
}
}
}
}
Example variables
{
"input": {
"packages": [
{
"id": "updatepackage-001",
"updates": {
"addTrackers": [
{
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"encodingFormat": "example",
"reuseTrackerSerial": false,
"serial": "E28011700000020ABC12345"
}
],
"comments": "Inspected and approved",
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"id": "package-001",
"locationId": "location-001",
"name": "Forklift 7",
"removeTrackerSerials": [
"E28011700000020ABC12345"
]
}
}
]
}
}
Example response
{
"data": {
"updatePackages": {
"packages": [
{
"comments": "Inspected and approved",
"containerId": "container-001",
"creationDate": 1719792000000,
"customProperties": "{\"weight\":\"15kg\",\"color\":\"blue\"}",
"description": "Electric counterbalance forklift",
"id": "package-001",
"lastDetectionDate": 1719792000000,
"lastUpdatedDate": 1719792000000,
"name": "Forklift 7",
"state": "ACTIVE",
"transferOrderId": "transferorder-001",
"transferStatus": "example",
"uuid": "uu-001",
"lastDetectedAtLocation": {
"id": "location-001",
"name": "Forklift 7"
},
"location": {
"id": "location-001",
"name": "Forklift 7"
},
"trackers": [
{
"serial": "E28011700000020ABC12345"
}
]
}
]
}
}
}

Arguments​

input · UpdatePackagesInput!

PackageUpdates​

Updatable fields for a package.

FieldTypeDescription
addTrackers[TrackerInput!]Trackers to attach to the package.
commentsStringAny comments or remarks recorded for the package.
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
descriptionStringFree-text description of the package.
idStringUnique identifier of the package.
locationIdStringIdentifier of the location the package is at.
nameStringDisplay name of the package.
removeTrackerSerials[String!]Tracker serials to detach from the package.
UpdatePackageInput​

A single package to update, identified by its ID.

FieldTypeDescription
idString!Unique identifier of the package to update.
updatesPackageUpdatesFields to update on the package.
UpdatePackagesInput​

Input for the updatePackages mutation.

FieldTypeDescription
packages[UpdatePackageInput!]!Packages to update.

Returns​

UpdatePackagesPayload

UpdatePackagesPayload​

Result of the updatePackages mutation.

FieldTypeDescription
packages[Package!]!The updated packages.

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.

Package​

A tracked package, identified by its package ID and optional tracker.

FieldTypeDescription
commentsStringAny comments or remarks recorded for the package.
containerIdStringIdentifier of the container holding this package, if any.
creationDateAWSTimestampEpoch-millisecond timestamp when the package was created.
customPropertiesAWSJSONAdditional custom properties, serialized as a JSON string.
descriptionStringFree-text description of the package.
idString!Unique identifier of the package.
lastDetectedAtLocationLocationV2Location where the package was last detected.
lastDetectionDateAWSTimestampEpoch-millisecond timestamp when the package was last detected.
lastUpdatedDateAWSTimestampEpoch-millisecond timestamp when the package was last updated.
locationLocationV2Current location of the package.
nameStringDisplay name of the package.
stateStringCurrent state of the package.
trackers[Tracker]Trackers currently attached to the package.
transferOrderIdStringIdentifier of the transfer order this package belongs to, if any.
transferStatusStringCurrent transfer status of the package.
uuidStringGlobally unique identifier of the package.

Tracker​

An identifier tracker (e.g. RFID tag or barcode) attached to a tracked item.

FieldTypeDescription
attachDateAWSTimestampEpoch-millisecond timestamp when the tracker was attached to the item.
customPropertiesAWSJSONTenant-specific sensor profile custom properties.
encodingFormatStringRFID tag encoding format for this tracker.
serialStringEPC or tracker serial identifying this tracker.

TrackerInput​

Input for specifying a tracker to attach when creating or updating an item. Replaces the per-field trackerSerial / reuseTrackerSerial pattern.

FieldTypeDescription
customPropertiesAWSJSONTracker-level custom properties as a JSON object.
encodingFormatStringRFID tag encoding format for this tracker.
reuseTrackerSerialBooleanWhether to reuse a tracker serial already attached to another item.
serialString!EPC or tracker serial to attach.