Skip to main content

Inventory and Purchase Orders via API

Create purchase orders, update their status and item states, receive inventory, and move inventory items between warehouses, team members, and patients.

Before You Start: Lookups

What you need

Endpoint

Example

Vendors

GET /v1/vendors

VR1b89c710acea37aa39249fcab4007a3f

Warehouses (inventory locations)

GET /v1/inventory-locations

LI133e5e00acea46095a34639c97805835

Products

GET /v1/products

A05MW34SX96ZF71QT28K

Units of measure

GET /v1/uoms, GET /v1/uoms/purchase

UMf659af00783b2b9b61e4ad120d15d60a

Purchase order statuses

GET /v1/purchase-orders/statuses

New, InProgress, Backorder, Fulfilled, Cancelled

💡 Purchase order statuses can include custom statuses your organization has set up. Always get the list from GET /v1/purchase-orders/statuses rather than hard-coding it.


Purchase Orders

Create a Purchase Order

POST /v1/purchase-orders

Fields

Field

Required

Notes

VendorId

✅

LocationId

✅

The receiving warehouse

Items

✅

One or more line items

Status

A status Id from GET /v1/purchase-orders/statuses

AccountNumber

Your account number with the vendor

ShippingAddress

Requires AddressLine, City, Zip

Notes

Line items

Field

Required

Notes

ProductId

✅

Qty

✅

UomId

✅

Purchase unit of measure

Price

✅

Unit price

Discount

Sku

Vendor SKU

LineNumber

Notes

Example

POST /v1/purchase-orders
{
"VendorId": "VR1b89c710acea37aa39249fcab4007a3f",
"LocationId": "LI133e5e00acea46095a34639c97805835",
"AccountNumber": "123456",
"Status": "New",
"Items": [
{
"ProductId": "A05MW34SX96ZF71QT28K",
"Qty": 10,
"UomId": "UMf659af00783b2b9b61e4ad120d15d60a",
"Price": 47.50,
"Sku": "CAH-12345",
"LineNumber": 1
}
]
}

Response: 201 Created

{ "Id": "POK35XW94MP10BG87QC6" }

Search Purchase Orders

GET /v1/purchase-orders

Filters: id, displayId, vendorId, vendorName, accountNumber, status, statuses, itemStatus, locationId, notes, createdBy, createdOn, customField.fieldId + customField.value, includeArchived, pageIndex, pageSize, selectCount.

{
"Items": [
{
"Id": "POK35XW94MP10BG87QC6",
"DisplayId": "PO-0BG87QC6",
"Status": { "Id": "Fulfilled", "Name": "Fulfilled" },
"Vendor": { "Id": "VR1b89c710acea37aa39249fcab4007a3f", "Name": "Cardinal Health" },
"TotalPrice": { "Amount": 475 },
"Archived": false
}
]
}

Get one: GET /v1/purchase-orders/{id}

Update a Purchase Order

PUT /v1/purchase-orders/{id}

Same fields as creating one, except Status. Include each existing line's Id to update it.

Change Status

PUT /v1/purchase-orders/{id}/status
{ "Status": "InProgress" }

Update Line Item States

PUT /v1/purchase-orders/{id}/items/states

Use this to record where each line item stands with the vendor, for example from a vendor integration.

Status

Detail block (required for that status)

Requested

Requested

Acknowledged

Acknowledged

AcknowledgeNotReceived

AcknowledgeNotReceived, with Messages (required)

Failed

Failed, with Messages (required)

Fulfilled

Each detail block accepts an optional Date and Metadata (any JSON object).

{
"Items": [
{
"PurchaseOrderItemId": "string",
"Status": "Acknowledged",
"Acknowledged": { "Date": "2026-11-10" }
},
{
"PurchaseOrderItemId": "string",
"Status": "Failed",
"Failed": { "Date": "2026-11-10", "Messages": ["Item discontinued by vendor"] }
}
]
}

Delete a Purchase Order

DELETE /v1/purchase-orders/{id}

Audit History

  • GET /v1/purchase-orders/{purchaseOrderId}/audit: the change history

  • GET /v1/purchase-orders/{purchaseOrderId}/audit/{auditId}/details: received items and order-item link details for an audit entry


Inventory Items

Receive Inventory

POST /v1/inventory-items/receive

Field

Required

Notes

ProductId

✅

LocationId

✅

The warehouse receiving the stock

Count

✅

In the selected unit of measure. Must be 1 for serialized products.

UomId

✅

SerialNumber

For serialized products

Leave out for other product types

LotNumber

For lotted products

Leave out for other product types

Components

For bundle products

One entry per component: ProductId, plus SerialNumber / LotNumber as needed

PurchaseOrderId

Link the receipt to a purchase order

PurchasePrice

Per unit of measure

DeviceNumber

Notes

POST /v1/inventory-items/receive
{
"ProductId": "A05MW34SX96ZF71QT28K",
"LocationId": "LI133e5e00acea46095a34639c97805835",
"Count": 1,
"UomId": "UMf659af00783b2b9b61e4ad120d15d60a",
"SerialNumber": "SN-0012345",
"PurchaseOrderId": "POK35XW94MP10BG87QC6",
"PurchasePrice": 47.50
}

Batch receive: POST /v1/inventory-items/batch/receive with { "Items": [ ... ] }, same item fields. This runs as a background job: the response returns a job ID. Check its progress with GET /v1/jobs/{id}.

Search Inventory

GET /v1/inventory-items

Filters: name, productIds, partNumber, serialNumber, lotNumber, hcpcsCode, status, locationType, locationId, location, manufacturer, manufacturerIds, groupIds, categoryIds, refurbished, serviceRequired, pageIndex, pageSize, selectCount.

{
"Items": [
{
"Id": "UN0160e7001c4b1c4b88d4a85abd7e0954",
"Name": "AirFit F20 Frame - Small",
"PartNumber": "63463",
"PrimaryHcpcsCodes": ["A7030"],
"ProductType": { "Id": "NonSerialized", "Name": "NonSerialized" },
"Count": 1,
"Status": { "Id": "Active", "Name": "Active" },
"Location": { "Id": "10000370", "Name": "Jane Doe", "Type": { "Id": "Patient", "Name": "Patient" } },
"Refurbished": false,
"ServiceRequired": false
}
]
}

Get one: GET /v1/inventory-items/{id}

Move Inventory

PUT /v1/inventory-items/{id}/move

Field

Required

Notes

Count

✅

UomId

✅

Destination.Type

✅

Warehouse, TeamMember, or Patient

Destination.Id

✅

Inventory location ID, team member ID (GET /v1/team-members), or patient ID

Notes

PUT /v1/inventory-items/UN0160e7001c4b1c4b88d4a85abd7e0954/move
{
"Count": 1,
"UomId": "UMf659af00783b2b9b61e4ad120d15d60a",
"Destination": { "Type": "Warehouse", "Id": "LI016c7a00f12b857bbc342d5fdedd63cc" },
"Notes": "Returned from patient"
}

Batch move: PUT /v1/inventory-items/batch/move with { "Items": [ ... ] }. Each item includes its InventoryItemId. It also runs as a background job; check GET /v1/jobs/{id}.


Related Setup Endpoints

Area

Endpoints

Vendors

GET/POST /v1/vendors, GET/PUT/DELETE /v1/vendors/{id}

Products

GET/POST /v1/products, GET/PUT /v1/products/{id}, /v1/products/{id}/vendors

Units of measure

GET/POST /v1/uoms, GET/PUT/DELETE /v1/uoms/{id}

Product categories, groups, manufacturers (V2)

/v2/inventory/categories, /v2/inventory/groups, /v2/inventory/manufacturers


Get Notified of Changes

Subscribe to purchase-order.created, purchase-order.updated, purchase-order.deleted, purchase-order.status.updated, and management.inventory.product.created / .updated / .deleted.


Common Errors

Code

Meaning

400

Invalid request, e.g. a missing serial number for a serialized product, a Count other than 1 for a serialized product, or a missing detail block for an item state

401

Token missing, expired, or invalid

403

You don't have permission to access this resource

404

Purchase order, item, product, vendor, or location not found

429

Too many requests


Related articles

Did this answer your question?