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.
| Field | Type | Description |
|---|---|---|
endDate | AWSTimestamp | Epoch-millisecond timestamp marking the end of the route window. |
id | String! | Unique identifier of the package whose route is requested. |
nextToken | String | Pagination token for fetching the next page of results. |
startDate | AWSTimestamp | Epoch-millisecond timestamp marking the start of the route window. |
Returns
PackageRoute
A single stop in a package's location route history.
| Field | Type | Description |
|---|---|---|
customProperties | AWSJSON | Additional custom properties, serialized as a JSON string. |
duration | AWSTimestamp | Duration the package spent at this stop. |
endDate | AWSTimestamp | Epoch-millisecond timestamp when the package left this stop. |
location | LocationV2 | Location of this route stop. |
startDate | AWSTimestamp | Epoch-millisecond timestamp when the package entered this stop. |
state | String | State of the package at this route stop. |
PackageRoutePayload
Result of the packageRoute query.
| Field | Type | Description |
|---|---|---|
nextToken | String | Pagination 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.
| Field | Type | Description |
|---|---|---|
packages | [PackageInput!]! | Packages to create. |
PackageInput
A single package to create.
| Field | Type | Description |
|---|---|---|
comments | String | Any comments or remarks recorded for the package. |
customProperties | AWSJSON | Additional custom properties, serialized as a JSON string. |
description | String | Free-text description of the package. |
id | String! | Serial or unique identifier for the package. |
locationId | String | Identifier of the location the package is at. |
name | String | Display name of the package. |
trackers | [TrackerInput!] | Trackers to attach to the package. |
Returns
CreatePackagesPayload
Result of the createPackages mutation.
| Field | Type | Description |
|---|---|---|
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.
| Field | Type | Description |
|---|---|---|
packageIds | [String!]! | Identifiers of the packages to delete. |
Returns
DeletePackagesPayload
Result of the deletePackages mutation.
| Field | Type | Description |
|---|---|---|
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.
| Field | Type | Description |
|---|---|---|
addTrackers | [TrackerInput!] | Trackers to attach to the package. |
comments | String | Any comments or remarks recorded for the package. |
customProperties | AWSJSON | Additional custom properties, serialized as a JSON string. |
description | String | Free-text description of the package. |
id | String | Unique identifier of the package. |
locationId | String | Identifier of the location the package is at. |
name | String | Display name of the package. |
removeTrackerSerials | [String!] | Tracker serials to detach from the package. |
UpdatePackageInput
A single package to update, identified by its ID.
| Field | Type | Description |
|---|---|---|
id | String! | Unique identifier of the package to update. |
updates | PackageUpdates | Fields to update on the package. |
UpdatePackagesInput
Input for the updatePackages mutation.
| Field | Type | Description |
|---|---|---|
packages | [UpdatePackageInput!]! | Packages to update. |
Returns
UpdatePackagesPayload
Result of the updatePackages mutation.
| Field | Type | Description |
|---|---|---|
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.
| 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. |
Package
A tracked package, identified by its package ID and optional tracker.
| Field | Type | Description |
|---|---|---|
comments | String | Any comments or remarks recorded for the package. |
containerId | String | Identifier of the container holding this package, if any. |
creationDate | AWSTimestamp | Epoch-millisecond timestamp when the package was created. |
customProperties | AWSJSON | Additional custom properties, serialized as a JSON string. |
description | String | Free-text description of the package. |
id | String! | Unique identifier of the package. |
lastDetectedAtLocation | LocationV2 | Location where the package was last detected. |
lastDetectionDate | AWSTimestamp | Epoch-millisecond timestamp when the package was last detected. |
lastUpdatedDate | AWSTimestamp | Epoch-millisecond timestamp when the package was last updated. |
location | LocationV2 | Current location of the package. |
name | String | Display name of the package. |
state | String | Current state of the package. |
trackers | [Tracker] | Trackers currently attached to the package. |
transferOrderId | String | Identifier of the transfer order this package belongs to, if any. |
transferStatus | String | Current transfer status of the package. |
uuid | String | Globally unique identifier of the package. |
Tracker
An identifier tracker (e.g. RFID tag or barcode) attached to a tracked item.
| Field | Type | Description |
|---|---|---|
attachDate | AWSTimestamp | Epoch-millisecond timestamp when the tracker was attached to the item. |
customProperties | AWSJSON | Tenant-specific sensor profile custom properties. |
encodingFormat | String | RFID tag encoding format for this tracker. |
serial | String | EPC 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.
| Field | Type | Description |
|---|---|---|
customProperties | AWSJSON | Tracker-level custom properties as a JSON object. |
encodingFormat | String | RFID tag encoding format for this tracker. |
reuseTrackerSerial | Boolean | Whether to reuse a tracker serial already attached to another item. |
serial | String! | EPC or tracker serial to attach. |