Create order

POST 
/api/v3/order

This endpoint is for creating orders linked to either a patient or a site, with order content specified by item or kit IDs and an association with a patient or site ID. Optional attributes offer further customization, such as tracking through external order IDs.\n\nFor site orders, the site must already exist in Impilo and the request must include site.id. Site name and address details are not used to create or look up a site during order creation. To create a new site, use POST /api/v3/site first, then use the returned id when creating the order.\n\nThis endpoint also supports two-way orders (outbound + return) by including returnDevices, returnItems, or returnPackedKits. When including returns without outbound items, at least one return field must be specified.\n\nFor a comprehensive guide on utilizing this endpoint, including examples, required and optional attributes, and additional functionalities like listing and fetching orders, visit the Order Management Guide.

Request

Responses

201

Order created successfully

400

Bad Request - Possible error messages:

Order Structure:

• "Order must contain at least one of: orderItems, orderKits, returnItems, returnDevices, or returnPackedKits"
• "shippingOption is required when emailLabel is false and return items are included"
• "patient or site required" - Site orders must include site.id; site details alone are not sufficient.

Inventory & Items:

• "insufficient_inventory" - No fulfillment site has enough inventory
• "Order contains Items that are marked as non-orderable. Order cannot be placed."
• "item_not_orderable"

Loaner Kit Rules:

• "max_one_loaner_kit" - Only one loaner kit allowed per order
• "qty_over_one_loaner_kit" - Loaner kit quantity must be 1
• "no_returns_with_loaner_kit" - Cannot combine returns with loaner kits
• "no_loaner_kit_to_site" - Loaner kits can only ship to patients, not sites

Returns:

• "Device cannot be included both as a return device and in a packed kit"

Patient/Site Validation:

• "patient_does_not_exist" - Patient ID not found for your customer
• "invalid_order" - Customer or site validation failed

New Patient Creation:

• "Patient required"
• "Must provide a non-blank string for firstName."
• "Must provide a non-blank string for lastName."
• "Must provide an Address for Patient."
• "Site {id} not found" / "Site {id} not active" / "Unable to find the Site provided."
• "Must provide a Line One value in the Address."
• "Must provide a City value in the Address."
• "Must provide a State value in the Address."
• "Must provide a Country value in the Address."
• "Must provide a Zip Code value in the Address."

Request Format:

• "Invalid JSON format" - Malformed JSON
• "Invalid data provided" - Data constraint violations

401

Unauthorized - Missing, invalid, or expired authentication token

403

Forbidden - Possible error messages:

• "Access Denied" - Insufficient permissions
• "The requested feature has been disabled." - Feature disabled for your account
• "The requested resource is forbidden." - Role-based access restriction