Place Order

Create an ITAD order with devices and ship-from address; optionally start box, label, or pickup recovery.

POST

/api/v1/itad/place-order

Description

Send a devices array and either flat shipping_* fields or corporate_address_id for the ship-from location.

Optionally set recovery_option to send_me_a_box (default when omitted), print_a_label, or request_pickup. Invalid recovery_option values return 422.

When print_a_label or request_pickup is selected, required recovery fields are validated before the order is created (422 on missing/invalid fields). Region or carrier unavailability soft-fails recovery after the order is created — check recovery_success.

Request

Headers

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

Body Parameters

Parameter	Type	Required	Example	Description
devices	array	Yes	—	Non-empty array of devices on the order. Alias: items (still accepted).
corporate_address_id	number \| string	No	—	Optional company location ID. When provided and valid, shipping fields are loaded from that location (alias: address_id). Location must have a phone number or the request returns 422.
shipping_name	string	Yes	—	Ship-from contact or company name (where devices are located). Not required when corporate_address_id is used.
shipping_address_1	string	Yes	—	Ship-from street address line 1. Not required when corporate_address_id is used.
shipping_address_2	string	No	—	Ship-from street address line 2.
shipping_city	string	Yes	—	Ship-from city. Not required when corporate_address_id is used.
shipping_state	string	Yes	—	Ship-from state or province. Not required when corporate_address_id is used.
shipping_country	string	Yes	—	Ship-from country code (e.g. US). Not required when corporate_address_id is used.
shipping_zip	string	Yes	—	Ship-from postal code. Not required when corporate_address_id is used.
shipping_phone	string	Yes	—	Ship-from phone (10–15 digits). Not required when corporate_address_id is used.
shipping_email	string	No	—	Shipping contact email.
notify_order	number \| boolean	No	—	Stored on the order as notify (0/1). When 1 or true, the attributed platform user receives order status notification emails for this order.
recovery_option	string	No	send_me_a_box	How devices should be recovered: send_me_a_box, print_a_label, or request_pickup. When omitted, defaults to send_me_a_box. Invalid values return 422.

Each object in devices[]

Fields

Parameter	Type	Required	Description
device_category	string \| number	Yes	Device category: 1=Mobile, 2=Tablet, 3=iPod, 4=Laptop, 5=Server, 6=Printers, 7=Desktop, 8=Network Gear, 9=Other. Also accepts names/aliases (e.g. phone, mobile, laptop, printers, network gear). Alias: device_type (same codes as List/Detail).
qty	number	Yes	Quantity (must be ≥ 1).
brand	string	Yes	Device brand (e.g. Apple, Dell).
model	string	Yes	Device model (e.g. MacBook Pro 14, Latitude 5520).

When recovery_option is print_a_label (required before create)

Fields

Parameter	Type	Required	Example	Description
number_of_labels	number	Yes	1	Number of shipping labels to generate (1–10).
weight_lbs	number	Yes	5	Package weight in pounds. Alias: w_pound.
weight_oz	number	Yes	0	Additional package weight in ounces. Alias: w_ounce. Combined weight must be greater than 0 and not exceed 150 lbs.
length_in	number	Yes	12	Package length in inches. Alias: d_length.
width_in	number	Yes	10	Package width in inches. Alias: d_width.
height_in	number	Yes	8	Package height in inches. Alias: d_height.

When recovery_option is request_pickup (required before create)

Fields

Parameter	Type	Required	Example	Description
pickup_firstname	string	Yes	—	Pickup contact first name. Alias: firstname.
pickup_lastname	string	Yes	—	Pickup contact last name. Alias: lastname.
pickup_email	string	Yes	—	Pickup contact email. Alias: email.
pickup_phone	string	Yes	—	Pickup contact phone (at least 10 digits). Alias: phone.
pickup_phone_country	string	Yes	US	Pickup phone country (ISO alpha-2). Alias: phone_country.
pickup_address_1	string	Yes	—	Pickup street address line 1. Alias: address_1.
pickup_address_2	string	No	—	Pickup street address line 2. Alias: address_2.
pickup_city	string	Yes	—	Pickup city. Alias: city.
pickup_state	string	Yes	—	Pickup state or province. Alias: state.
pickup_country	string	Yes	—	Pickup country. Alias: country.
pickup_zip	string	Yes	—	Pickup postal code (5–10 characters). Alias: zip.
pickup_date	string	Yes	06/15/2026	Requested pickup date (MM/DD/YYYY or YYYY-MM-DD).
pickup_time	string	Yes	10:00:00	Preferred pickup time (HH:MM:SS, e.g. 10:00:00).
pickup_service	string	Yes	inside_pickup	Pickup service type. Must be inside_pickup (inside pickup) or liftgate_service_pickup (liftgate services at pickup).
pickup_description	string	Yes	—	Packaging details: pallets, gaylords, box counts, etc. Alias: description.
is_freight_elevator	boolean	No	false	Freight elevator available at pickup. Default false.
forklift_available	boolean	No	false	Forklift available at pickup. Default false.
liftgate_required	boolean	No	false	Liftgate service required for this pickup. Default false.
pickup_weight	string	No	—	Total shipment weight in lbs. Alias: weight.

Example Request Body

{
  "devices": [
    {
      "device_category": 4,
      "qty": 2,
      "brand": "Apple",
      "model": "MacBook Pro 14"
    },
    {
      "device_category": "phone",
      "qty": 5,
      "brand": "Samsung",
      "model": "Galaxy S23"
    }
  ],
  "shipping_name": "Acme Corp IT",
  "shipping_address_1": "500 Logistics Way",
  "shipping_address_2": "Suite 200",
  "shipping_city": "San Jose",
  "shipping_state": "CA",
  "shipping_country": "US",
  "shipping_zip": "95110",
  "shipping_phone": "4085551234",
  "shipping_email": "[email protected]",
  "recovery_option": "send_me_a_box"
}

Response

Field	Type	Description
message	string	Human-readable result. Check recovery_success — do not rely on message text alone.
order_number	string	Numeric order number for List, Detail, and Cancel.
order_id	string	ITAD order ID, externally encoded as {7-digit-prefix}-{numericId}.
recovery_option	string	Recovery option that was applied (send_me_a_box, print_a_label, or request_pickup).
recovery_success	boolean	True when recovery completed. False when the order was created but recovery could not run (e.g. region/carrier unavailable). HTTP status is still 200 when the order is created.
recovery_error	string \| null	Null on success. Otherwise a machine-readable code such as region_unavailable, label_generation_failed, or recovery_failed.

Notes

Prefer devices[]. items[] is accepted as a back-compat alias.
shipping_* fields are required unless corporate_address_id (or address_id) points to a valid company location with a phone number.
Company billing must be complete in settings; when Configure has the ship-from country enabled, an active work instruction is required (otherwise 422).
Orders are attributed to the company's default platform user (not the API JWT developer account).
recovery_option omitted → send_me_a_box. Unknown values → 422.
print_a_label / request_pickup required fields are enforced with 422 before the order is created.
Available recovery options depend on logistics/carrier configuration for the ship-from country (e.g. print_a_label currently needs UPS; Mexico typically only supports request_pickup).
Always check recovery_success on HTTP 200. recovery_error is a machine-readable code when recovery_success is false.
List/Detail return shipping.address / shipping.apt for the same data sent as shipping_address_1 / shipping_address_2.
notify_order (optional, 0 or 1): when truthy, sets the order notify flag so the attributed platform user receives order status notifications.

Request

curl -X POST https://dev-api.unduit.com/api/v1/itad/place-order \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "devices": [
      {
        "device_category": 4,
        "qty": 2,
        "brand": "Apple",
        "model": "MacBook Pro 14"
      },
      {
        "device_category": "phone",
        "qty": 5,
        "brand": "Samsung",
        "model": "Galaxy S23"
      }
    ],
    "shipping_name": "Acme Corp IT",
    "shipping_address_1": "500 Logistics Way",
    "shipping_address_2": "Suite 200",
    "shipping_city": "San Jose",
    "shipping_state": "CA",
    "shipping_country": "US",
    "shipping_zip": "95110",
    "shipping_phone": "4085551234",
    "shipping_email": "[email protected]",
    "recovery_option": "send_me_a_box"
  }'

Success Response

{
  "message": "Order placed successfully",
  "order_number": "174894512345",
  "order_id": "4829103-12345",
  "recovery_option": "send_me_a_box",
  "recovery_success": true,
  "recovery_error": null
}

Error Responses

422 Validation Error

{
  "success": false,
  "message": "devices is required and must be a non-empty array",
  "errors": {
    "devices": "devices is required and must be a non-empty array"
  }
}

422 Invalid recovery_option

{
  "success": false,
  "message": "recovery_option must be one of: send_me_a_box, print_a_label, request_pickup",
  "errors": {
    "recovery_option": "recovery_option must be one of: send_me_a_box, print_a_label, request_pickup"
  }
}

422 Missing print_a_label fields

{
  "success": false,
  "message": "number_of_labels must be between 1 and 10",
  "errors": {
    "number_of_labels": "number_of_labels must be between 1 and 10"
  }
}

422 Billing or work instruction missing

{
  "success": false,
  "message": "Your billing information is missing. Please update it in your settings before proceeding."
}

Place Order

Description

Request

Headers

Body Parameters

Each object in devices[]

Fields

When recovery_option is print_a_label (required before create)

Fields

When recovery_option is request_pickup (required before create)

Fields

Example Request Body

Response

Notes

Related Endpoints

Order List

Order Detail

Cancel Order

Request

Success Response

Error Responses

422 Validation Error

422 Invalid recovery_option

422 Missing print_a_label fields

422 Billing or work instruction missing