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 name	Type	Required/optional	Format
firstName	string	required
lastName	string	required
email	string	required	max length 60
phoneNumber	string	required
addressLine1	string	required	max length 35
addressLine2	string	optional	max length 35
city	string	required	max length 35
countryCode	enum	required	currently always NO
postalCode	string	required	4 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 name	Type	Description
updatedAt	Date	ISO-date
orderStatus	enum	ORDERED, IN_PROGRESS, SHIPPED or CANCELLED
deviceId	string or undefined	undefined until orderStatus is SHIPPED, then string
trackingLink	string or undefined	undefined 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",
        },
        //...
      ]
    }
  }
}