Hopp til innhold

Ordering devices

To be able to create, read or cancel device orders through our API, you need an API key with specific permissions. Please contact us to obtain the required permissions.

Ordering a device

The ordering process starts with the following mutation:

mutation {
orderDevice(
input: {
recipient: {
firstName: "Ola"
lastName: "Nordmann"
email: "ola@nordmann.no"
phoneNumber: "99999999"
externalUserId: "user_1"
postalAddress: {
addressLine1: "Christian Krohgs gate 1"
addressLine2: null
city: "OSLO"
postalCode: "0186"
country: NO
}
}
subscriptionType: PERSONAL
type: HAN_LTEM
webhookCallbackUrl: "https://example.com/callback"
}
) {
order {
orderId
orderStatus
}
ordersForUser {
orderId
orderStatus
}
}
}

The input fields subscriptionType and type are required enums, and specify the subscription type and device type, respectively. The first will be either PERSONALor BUSINESS, depending on the device recipient. The latter will be either HAN_LTEM or HAN_WIFI, depending on whether the device recipient has ordered a 4G or a WiFi device.

There is an optional webhookCallbackUrl field for which we will push updates about the order. The webhook will receive these data:

  • externalUserId,
  • orderId,
  • deviceType,
  • deviceId,
  • trackingLink,
  • orderStatus,

The last input field, recipient, is the one who has ordered the device. In addition to contact information and postal address, which is needed for shipping, we need an external user ID. This is any (unique) ID that will link orders with your customer - and can later be used as input for the orderForUser-query described below to list any orders associated with your customer.

The postal service that is used to ship devices is Bring, which sets some requirement for the recipient schema:

Field nameTypeRequired/optionalFormat
firstNamestringrequired
lastNamestringrequired
emailstringrequiredmax length 60
phoneNumberstringrequired
addressLine1stringrequiredmax length 35
addressLine2stringoptionalmax length 35
citystringrequiredmax length 35
countryCodeenumrequiredcurrently always NO
postalCodestringrequired4 digits if countryCode is NO

When running the mutation (with an api key with the right permissions), you’ll get a response that contains two parts; the new order, and a list of orders associated with the recipient (based on the externalUserId that you have provided).

note

The newly placed order will be included in this list.

An order will look like the orderDevice-input, but with two or, if shipped, four, additional fields:

Field nameTypeDescription
updatedAtDateISO-date
orderStatusenumORDERED, IN_PROGRESS, SHIPPED or CANCELLED
deviceIdstring or undefinedundefined until orderStatus is SHIPPED, then string
trackingLinkstring or undefinedundefined until orderStatus is SHIPPED, then string

The order status reflects what the progress of the order is. When it’s ORDERED, the order has not yet been processed. When it’s in this state, you can still cancel the order (see below). If the order status is IN_PROGRESS, the shipping process has begun, and it will not be long until the order is SHIPPED. The order cannot be cancelled when in these states.

The list of orders associated with the recipient in the response can be used to see if there’s already registered orders on the user, in which case you can choose to cancel an order.

Cancelling an order

To cancel an order, the order must be in order state ORDERED. If it's in any other order state, you'll get an error, as the order has already been processed.

The mutation cancelOrder only requires an order ID as input, and the response is the recently cancelled order-object.

mutation {
cancelOrder(
input: { orderId: "order_c1d5a4b4-e558-4834-9b6e-7aefe04033ba" }
) {
orderId
orderStatus
}
}

Getting an existing order

Currently, there are two ways of querying for orders.

Getting a specific order

Using an order ID, you query an order:

query {
order(input: { orderId: "order_1" }) {
orderId
orderStatus
}
}

The response will be the relevant order:

{
"data": {
"order": {
"orderId": "order_1",
"orderStatus": "SHIPPED",
"intermediaryId": "HARK",
"updatedAt": "2023-05-02T07:38:44.261Z",
"subscriptionType": "PERSONAL",
"type": "HAN_LTEM",
"recipient": {
"firstName": "Ola",
"lastName": "Nordmann",
"email": "ola@nordmann.com",
"phoneNumber": "99999999",
"postalAddress": {
"addressLine1": "Christian Kroghs gate 1",
"addressLine2": null,
"city": "OSLO",
"postalCode": "0186",
"country": "NO"
}
},
"trackingLink": "https://example.com/tracking",
"webhookCallbackUrl": "https://example.com/callback",
}
}
}

Get orders for a customer

It is also possible to list out all the orders associated with a user. The endpoint takes an external user ID as input:

query {
ordersForUser(input: { externalUserId: "user_1" }) {
orders {
orderId
orderStatus
}
}
}

The response will be a list of the user's orders:

{
"data": {
"ordersForUser": {
"orders": [
{
"orderId": "order_1",
"orderStatus": "SHIPPED",
"intermediaryId": "HARK",
"updatedAt": "2023-05-02T07:38:44.261Z",
"subscriptionType": "PERSONAL",
"type": "HAN_LTEM",
"recipient": {
"firstName": "Ola",
"lastName": "Nordmann",
"email": "ola@nordmann.com",
"phoneNumber": "99999999",
"postalAddress": {
"addressLine1": "Christian Kroghs gate 1",
"addressLine2": null,
"city": "OSLO",
"postalCode": "0186",
"country": "NO"
}
},
"trackingLink": "https://example.com/tracking",
"webhookCallbackUrl": "https://example.com/callback",
},
//...
]
}
}
}