Order update notifications

Withings API provides notification system to keep you informed of any order updates.

Important
  • In order to receive order update notifications you may need to contact your network administrator to make sure connections from Withings IP addresses are permitted. Refer to the TXT record from ipblock-notify.withings.net for the range(command: dig +short TXT ipblock-notify.withings.net). Withings will update this record at least one week prior to any change. Make sure you monitor it. Please contact us if your app is hosted on our HIPAA/HDS Cloud.
  • Notifications are sent as POST calls with parameters set in the body request as form-data parameters (not in the URL).

How to receive order update notifications

To implement the notification system, you must provide the Dropshipment notify URI in your Developer dashboard or HIPAA Developer dashboard if you are working with the HIPAA cloud.

The notification will be sent to your dropshipment notify URL by default (no subscription required).

Description of parameters

The following table describes the POST parameters that the Withings server will send to your callback URL upon a notification request.

NameTypeDescription
customer_idstringYour dropshipment billing ID
customer_refstringRandom identifier provided in Dropshipment v2 - Createorder or Dropshipment v2 - Createuserorder
statusstringOrder status (only before it is shipped)
parcel_statusstringParcel status (only once the order has been shipped)
carrierstringCourier (only if the order has been shipped)
carrier_servicestringCourier service (only if the order has been shipped)
tracking_numberstringTracking number (only if the order has been shipped)

Possible order status (see status)

Before an order is sent to our shipping services, you will be notified of preparation updates through the status property. This property can take the following values :

statusdescription
ADDRESS ERRORthe address provided is not a valid address. This status will be returned synchronously when calling the createorder or createuserorder API. If one or more orders qualify as "ADDRESS ERROR", the request will fail and the orders won't be created in Withings systems. If status returned is ADDRESS ERROR and you still want Withings to process the order, please retry the request and use the force_address option in the order model.
VERIFIEDthe address provided is a valid address.
PROCESSINGthe order is being sent to Withings logistics.
FAILEDthe order failed to be sent to Withings logistics.
OPENthe order was successfully received by Withings logistics
SHIPPEDthe order was shipped to the address provideds
TRASHEDthe order has been cancelled. This status will be returned through order update notification. Please contact Withings if you think your order has been cancelled by mistake.
BACKHOLDthe order is on hold. This can happen for different reason (unavailable product, delays in supply chain...).
To better understand the life cycle of an order and the possible status sequences, please refer to the diagram below:
Order state machine
Order state machine
*more info about the force_adress parameter can be found here

Possible delivery statuses (see parcel_status)

Once the order has been transmitted to the shipping service, you will be notified of delivery updates through the parcel_status property. This property can take the following values :

parcel_statusdescription
pendingNo delivery event has been received for this package yet. It might not be yet handled to the shipping carrier, or the carrier didn't register it in its IT system yet
info_receivedShipping carrier acknowledged the creation of the shipping label but the package is not yet in its shipping network
in_transitShipping has started and the package is in transit
failed_attemptA delivery attempt occurred but the package could not be delivered. It is still in the shipping carrier's network
exceptionAn exception occurred. Most of the time, it will be a delivery incident
delayedThe package is still in transit but it has exceeded its expected delivery date
pickupThe package is available for retrieval at a pickup point
deliveredThe package has been delivered or collected from a pickup point
returnThe package will be returned to sender. We will continue retrieving events for 5 days after the first return event
expiredThe package was created more than 45 days ago but is still not delivered. We will not look for more events for this package. Possible causes are: - The package was never shipped - No delivery event was registered in the carrier IT system