Place Order

Creates a new order with product, customer, and shipping details.

POST

/api/v1/device-hub/place-order

Description

Submit an order to deploy IT assets to employees. Specify the products, shipping method, and recipient details to create a new deployment order. Set attach_recovery to true and include arecovery object to create a linked Recover employee on the same request. When attach_recovery is false or omitted, recovery is skipped.

Request

Headers

Header	Value	Required
Authorization	Bearer <token>	Yes
Content-Type	application/json	Yes

Request Body

Field	Type	Required	Description
products	array	Yes	List of products to order
products[].name	string	Yes	Exact product name from inventory
products[].quantity	integer	Yes	Quantity to order
email	string	Yes	Customer email address
firstname	string	Yes	Customer first name
lastname	string	Yes	Customer last name
shipping_address	string	Yes	Street address for delivery
shipping_city	string	Yes	City for delivery
shipping_state	string	Yes	State/Province (if applicable)
shipping_zip	string	Yes	Postal/ZIP code
shipping_country	string	Yes	Country code (ISO2, e.g., US)
phone_number	string	Yes	Contact number of the recipient
expedite_shipping	string / null	No	Shipping method (e.g., "2nd Day Air", "Overnight"). Must match warehouse options.
is_signature_required	boolean	No	Whether delivery signature is required (US and CA only)
shipment_protection_enabled	boolean	No	Whether to add shipment protection to the order. Defaults to false when omitted. Supported only for orders fulfilled from warehouses in the United States, Canada, Germany, or the United Kingdom.
shipment_protection_declared_value	number	Conditional	Declared value used for shipment protection. Required and must be greater than 0 and not exceed 50,000 when `shipment_protection_enabled` is true. Ignored when `shipment_protection_enabled` is false.
tag	object / string	No	Optional accounting tags. May be a JSON object or JSON-encoded string.
tag.cost_center_code	string	No	If a cost center with this code does not exist for your company, a new cost center is created and linked to the order.
tag.department	string	No	If a department with this name does not exist for your company, a new department is created and linked to the order. Alias: `tag.department_name`.
tag.gl_code	string	No	GL code. Max 50 characters.
tag.po_number	string	No	PO number. Max 50 characters.
tag.site	string	No	Site. Max 100 characters.
tag.custom_field_1	string	No	Custom field 1. Max 255 characters.
tag.custom_field_2	string	No	Custom field 2. Max 255 characters.
attach_recovery	boolean	No	When true, validates and attaches linked recovery from the `recovery` object. When false or omitted, places a normal Device Hub order and skips recovery even if `recovery` is present.
recovery	object	Conditional	Required when `attach_recovery` is true. Creates a Recover employee and links it to the new Device Hub order.
recovery.campaign_number	string / integer	Conditional	Recover campaign number. Required when `attach_recovery` is true. Must be an active Recover campaign for your company.
recovery.asset_name	string	Conditional	Name of the single asset to recover (max 100 characters). Required when `attach_recovery` is true. Stored as the recovery employee `item_1`. Does not accept initiate-recovery `items[]` fields.
recovery.recovery_reason	integer	No	Recovery reason: 1 Refresh, 2 Break/Fix, 3 Offboarding, 4 Other. Same semantics as Initiate Recovery.
recovery.recovery_reason_note	string	Conditional	Required when `recovery_reason` is 4 (Other). Max 255 characters.

Response Fields

Field	Type	Description
message	string	Confirmation message
data.orderid	string	Unique order number
data.products	array	Ordered products with details
data.products[].name	string	Product name
data.products[].quantity	integer	Quantity ordered
data.products[].price	number	Unit price
data.products[].image	string	URL to product image
data.recovery	object	Present only when `attach_recovery` is true and recovery was created
data.recovery.recovery_code	string	Recovery number for the linked Recover employee
data.recovery.campaign_number	string	Recover campaign number used for the linked employee

Notes

The products[].name value must exactly match the name returned from the Inventory List endpoint
If expedite_shipping is specified, it must match one of the shipping options from the warehouse
Valid shipping options: "UPS Ground", "2nd Day Air", "Overnight"
is_signature_required only applies to US and CA shipments
Shipment protection is only supported for orders fulfilled from United States, Canada, Germany, and United Kingdom warehouses
When shipment_protection_enabled is true, shipment_protection_declared_value is required and must be greater than 0 and not exceed 50,000
When shipment_protection_enabled is false (or omitted), any shipment_protection_declared_value sent is ignored and no protection is stored
The orderid can be used to track the order status
Ensure the shipping_country uses ISO2 country codes (e.g., US, CA, GB)
The tag object is optional; when omitted, no order_tags row is created
If a cost center with tag.cost_center_code does not exist for your company, a new cost center is created and linked to the order
If a department with tag.department (or tag.department_name) does not exist for your company, a new department is created and linked to the order
Use GET /api/v1/departments to list existing department names, or pass a new name to create one
Set attach_recovery to true to create a linked Recover employee at place-order time using the shipping contact fields; when false or omitted, recovery is skipped
recovery is required when attach_recovery is true; recovery.asset_name is a single asset name only (not Initiate Recovery items[] with serial/IMEI/legal hold)
When attach_recovery is true, tag.department (or tag.department_name) is reused for the linked recovery employee when present; if tag has no department, no department is attached to recovery
Invalid attach_recovery, recovery.campaign_number, asset_name, or recovery_reason returns 4xx and does not create the Device Hub order or recovery employee