Ship pre-configured devices

Now that we know how to sign requests, we can create of first order for pre-configured device(s).

The createuserorder webservice allows partners to ship preconfigured devices to their users by leveraging Withings Logistics services. This API serves the following purposes:

Create a Withings user account
Place a dropshipment order for device(s) specified in the request
Preconfigure the cellular device(s) for the user

Notes

Invalid addresses in the order will result in the entire request being rejected.
The authorization code returned in this API is valid for 10 minutes.

Once you've created the order and user, you can proceed to the next step to learn how to exchange the code for access and refresh tokens.

Parameters

Refer to the API reference or

Toggle me!

Parameter	Required	Type	Description
action	Yes	string	The service action name. Must be set to `createuserorder`.
client_id	Yes	string	The ID of your client.
nonce	Yes	string	A random token used to prevent replay attacks. Refer to the Signature v2 - Getnonce.
signature	Yes	string	A hash of the parameters. See Signature hash protocol for details.
mailingpref	Yes	boolean	Indicates whether the customer has accepted Withings commercial contacts.
birthdate	Yes	integer	The Unix timestamp of the user's birthdate.
measures	Yes	json_string	User measures (refer to Measures model).
gender	Yes	integer	Gender of the user: `0` for male, `1` for female.
preflang	Yes	string	User's language preference (e.g., `en_EN`, `fr_FR`).
unit_pref	Yes	json	User's unit preferences (refer to Unit preferences model).
email	Yes	email	The user's email address.
timezone	Yes	timezone	User's timezone (e.g., `Europe/Paris`, `America/New_York`). A complete list can be found here.
shortname	Yes	string	A three-character representation of the end user (e.g., `ROB` for Robert). Must match regex: `/^[a-zA-Z0-9]{3}$/`.
external_id	Yes	string	A unique identifier used by the partner to identify the end user.
order	Yes	json	Order details (refer to Order model).
testmode	No	integer	Enable test mode to simulate order creation without shipping physical devices.

Order Model

The order parameter in the Dropshipment service is a list of JSON objects representing product purchase orders. Each order must contain the following information:

Order

Name	Type	Required	Description
customer_ref_id	string	Yes	A unique identifier for the order provided by the partner. It is used to track the order.
address	json	Yes	Delivery information for the order. Refer to the Address section below for details.
products	json	Yes	A list of products in the order. Refer to the Products section below for details.
force_address	boolean	No	If `true`, the address will not be validated by carriers. Default is `false`.

Address

Name	Type	Required	Description
name	string	Yes	Full name of the recipient.
company_name	string	No	Name of the company (if applicable).
email	string	Yes	Email address of the recipient.
telephone	string	No	Phone number in E.164 format.
address1	string	Yes	Primary address (e.g., street address with number).
address2	string	No	Additional address details (e.g., apartment or suite number).
city	string	Yes	City of the recipient.
zip	string	Yes	ZIP or postal code.
state	string	No	State of the recipient (ISO2 format).
country	string	Yes	Country of the recipient (ISO2 format).

Products

Name	Type	Required	Description
quantity	integer	Yes	Quantity of the product in the order.
ean	string	No	Product's international article number. Required if `partner_ref` is not used.
partner_ref	string	No	The reference of the Withings device kit shared during the project. Required if `ean` is not used.

Note: Either ean or partner_ref must be provided for each product.

Example

Below is an example of the order parameter in JSON format:

[
  {
    "customer_ref_id": "UNIQUE_ORDER_123",
    "address": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "telephone": "+1234567890",
      "address1": "123 Main Street",
      "address2": "Apt 4B",
      "city": "New York",
      "zip": "10001",
      "state": "NY",
      "country": "US"
    },
    "products": [
      {
        "quantity": 1,
        "partner_ref": "WITHINGS_DEVICE_KIT_001"
      },
      {
        "quantity": 2,
        "ean": "1234567890123"
      }
    ]
  },
  {
    "customer_ref_id": "UNIQUE_ORDER_456",
    "address": {
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "address1": "456 Elm Street",
      "city": "San Francisco",
      "zip": "94107",
      "country": "US"
    },
    "products": [
      {
        "quantity": 3,
        "partner_ref": "WITHINGS_DEVICE_KIT_002"
      }
    ]
  }
]

Snippet

const axios = require('axios');
const { sign, getNonce } = require('../signature');

// Constants
const API_ENDPOINT = 'https://wbsapi.withings.net/';
const OAUTH2_GRANT_TYPE_AUTHORIZATION_CODE = 'authorization_code';
const REDIRECT_URI = 'YOUR_REDIRECT_URI';
const CLIENT_ID = 'YOURCLIENTID';
const CLIENT_SECRET = 'YOURCLIENTSECRET';

const MEASURE_TYPE_HEIGHT = 4;
const MEASURE_TYPE_WEIGHT = 1;
const UNIT_HEIGHT_M  = 6;
const UNIT_HEIGHT_IN = 7;
const UNIT_WEIGHT_KG = 1;
const UNIT_WEIGHT_LB = 2;
const UNIT_WEIGHT_STLB = 14;
const UNIT_DISTANCE_KM = 6;
const UNIT_DISTANCE_YD = 8;
const UNIT_TEMPERATURE_C = 11;
const UNIT_TEMPERATURE_F = 13;

const TESTMODE_SHIPPED = 1;
const TESTMODE_TRASHED= 2;
const TESTMODE_FAILED = 3;
const TESTMODE_BACKHOLD = 4;


async function createUserOrder(nonce, order, user, testmode) {
  const params = {
    action: 'createuserorder',
    client_id: CLIENT_ID,
    nonce,
    order: JSON.stringify([order]), // order should always be passed a JSON array of Order objects
    email: user.email,
    shortname: user.shortname,
    gender: user.gender,
    birthdate: user.birthdate,
    measures: JSON.stringify(user.measures),
    external_id: user.external_id,
    mailingpref: user.mailingpref,
    unit_pref: JSON.stringify(user.unit_pref),
    preflang: user.preflang,
    timezone: user.timezone,
  };
  if (user.firstname) {
    params.firstname = user.firstname;
  }
  if (user.lastname) {
    params.lastname = user.lastname;
  }
  if (user.phonenumber) {
    params.phonenumber = user.phonenumber
  }
  if (user.goals) {
    params.goals = user.goals;
  }
  if (user.recovery_code) {
    params.recovery_code = user.recovery_code;
  }
  if (testmode !== null) {
    params.testmode = testmode;
  }
  params.signature = sign(params, CLIENT_SECRET);
  const { data } = await axios.post(API_ENDPOINT + 'v2/dropshipment', params);
  return data;
}

async function main() {
  const address   = {
    name: 'John Doe',
    company_name: 'Company',
    email: 'john.doe@example.com',
    telephone: '+551155256325',
    address1: '767 5th Ave',
    address2: 'Apt 101',
    city: 'Issy-les-Moulineaux',
    zip: '10153',
    state: 'NY',
    country: 'FR'
  };
  const products  = [
    {
      ean: '3700546707100',
      quantity: 1
    }
  ];
  const measures  = [
    { value: 190, unit: -2, type: MEASURE_TYPE_HEIGHT }, //1m90
    { value: 90, unit: 0, type:  MEASURE_TYPE_WEIGHT} //90kg
  ];
  const order     = {
    customer_ref_id: 'customer-ref-id', //the id of this order on your side
    address,
    products,
    force_address: true,
  };
  const unit_pref = { weight: UNIT_WEIGHT_KG, height: UNIT_HEIGHT_M, distance: UNIT_DISTANCE_KM, temperature: UNIT_TEMPERATURE_C };
  const mandatory_params_user = {
    mailingpref: 0,
    birthdate: 848166152,
    measures, // measurements should always be passed in kg/m
    gender: 0,
    preflang: 'en_US',
    unit_pref,
    email: 'john.doe@example.com',
    timezone: 'America/New_York',
    shortname: 'HNI',
    external_id: 'my-external-id' //id of this user on your side
  }
  const optional_params_user  = {
    firstname: 'John', //if not set, will take the same value as shortname
    lastname: 'Doe', //if not set, will take the same value as shortname
    phonenumber: '+551155256325', //Phone number in E.164 format.
    recovery_code: 'abcde12345',
    goals: null
  }
  const user = {...mandatory_params_user, ...optional_params_user};
  const now = Math.round((Date.now() / 1000));
  const response = await createUserOrder(await getNonce(now), order, user, TESTMODE_FAILED);
  console.log(JSON.stringify(response));
}

main();

module.exports = {
  createUserOrder
}

Response

{
    "status": 0,
    "body": {
        "user": {
            "code": "4ab52f3da1e1c8da346ec68ff26a45104c4859f6",
            "external_id": "my-external-id"
        },
        "orders": [
            {
                "orderid": "123456",
                "status": "SHIPPED",
                "address": {
                    "name": "John Wayne",
                    "email": "john.wayne@example.com",
                    "city": "New York"
                }
            }
        ]
    }
}

Solutions

Integration Guides

Tutorials

API Upgrades