curl -sS -X PATCH 'https://apipub.firstbasehq.com/api/v1/inventory/{inventoryId}' \
-H 'Authorization: ApiKey YOUR_API_KEY' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"deployStatus": "ARCHIVED",
"deployReason": "GIFTED_BY_EMPLOYER",
"assignedTo": {
"id": "00000000-0000-0000-0000-000000000000",
"type": "OFFICE"
},
"condition": "NEW",
"renewalDate": "2027-01-15",
"serialNumber": "SN-ABC-123",
"description": "Refurbished MacBook Pro 14\"",
"vendorCode": "APPLE",
"vendorSku": "MBP14-M3-512"
}'import requests
url = "https://apipub.firstbasehq.com/api/v1/inventory/{inventoryId}"
payload = {}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://apipub.firstbasehq.com/api/v1/inventory/{inventoryId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "ecb7e933-de1e-9830-b180-b25d1d0d296e",
"skuId": "203a5df2-423a-43a9-bb19-1ccaf3434b91",
"imei": [
356789012345678
],
"deployStatus": "ARCHIVED",
"condition": "NEW",
"categoryCode": "TSHIRT",
"categoryNameOfSku": "T-shirt",
"skuTitle": "T-shirt White - 5XL",
"vendorCode": "AWESOME_MERCHANDISE",
"vendorSku": "TSHRT_5XL_WHITE",
"createdAt": "2023-02-09T00:00:00",
"updatedAt": "2023-03-02T17:39:01.650027",
"tags": [
{
"id": "8e0caa73-cc71-4aa4-88eb-fca494de8e20",
"label": "Engineering"
}
],
"serialNumber": "25f2e6ea9a",
"deployReason": "LOST_BY_WORKER",
"renewalDate": "2026-02-09",
"renewalDateUpdatedBy": "RENEWAL_DATE_ORGANIZATION_LEVEL",
"billingStartDate": "2026-02-09",
"billingEndDate": "2028-02-09",
"procurementMethod": "Inventory Order - #c853d81c-ba0b-4027-a394-d5586b61608c",
"returnOrder": {
"id": "371da231-5878-45b1-80a3-9113f8795c29",
"status": "PENDING",
"createdAt": "2023-11-07T05:31:56Z",
"returnOrderItemId": "371da231-5878-45b1-80a3-9113f8795c29",
"returnOrderItemStatus": "PENDING",
"retrievalMethod": {
"type": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "REQUESTED",
"inboundTrackingCode": "1Z999AA10123456784",
"inboundTrackingLink": "<string>",
"updatedAt": "2023-11-07T05:31:56Z"
}
},
"assignedTo": {
"id": "371da231-5878-45b1-80a3-9113f8795c29",
"type": "PERSON",
"label": "jane@example.com",
"assignedAt": "2023-11-07T05:31:56Z"
},
"pricing": {
"regionCode": "<string>",
"priceOption": "<string>",
"price": 123,
"currencyCode": "<string>",
"discountedPrice": 123,
"discountPercentage": 123
},
"description": "Custom inventory description",
"netsuiteInvoiceId": "INV-123456",
"holdStartDate": "2023-12-25",
"unlockDate": "2023-12-25",
"itadRequested": true,
"appleBusiness": {
"assignmentStatus": "ASSIGNED",
"nextSyncTimestamp": "2026-07-02T02:00:00Z",
"lastSyncTimestamp": "2026-07-01T12:00:00Z"
}
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}Update inventory
Partially updates inventory attributes for a single item owned by the caller’s organization. Only fields present in the body are changed.
curl -sS -X PATCH 'https://apipub.firstbasehq.com/api/v1/inventory/{inventoryId}' \
-H 'Authorization: ApiKey YOUR_API_KEY' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"deployStatus": "ARCHIVED",
"deployReason": "GIFTED_BY_EMPLOYER",
"assignedTo": {
"id": "00000000-0000-0000-0000-000000000000",
"type": "OFFICE"
},
"condition": "NEW",
"renewalDate": "2027-01-15",
"serialNumber": "SN-ABC-123",
"description": "Refurbished MacBook Pro 14\"",
"vendorCode": "APPLE",
"vendorSku": "MBP14-M3-512"
}'import requests
url = "https://apipub.firstbasehq.com/api/v1/inventory/{inventoryId}"
payload = {}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://apipub.firstbasehq.com/api/v1/inventory/{inventoryId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "ecb7e933-de1e-9830-b180-b25d1d0d296e",
"skuId": "203a5df2-423a-43a9-bb19-1ccaf3434b91",
"imei": [
356789012345678
],
"deployStatus": "ARCHIVED",
"condition": "NEW",
"categoryCode": "TSHIRT",
"categoryNameOfSku": "T-shirt",
"skuTitle": "T-shirt White - 5XL",
"vendorCode": "AWESOME_MERCHANDISE",
"vendorSku": "TSHRT_5XL_WHITE",
"createdAt": "2023-02-09T00:00:00",
"updatedAt": "2023-03-02T17:39:01.650027",
"tags": [
{
"id": "8e0caa73-cc71-4aa4-88eb-fca494de8e20",
"label": "Engineering"
}
],
"serialNumber": "25f2e6ea9a",
"deployReason": "LOST_BY_WORKER",
"renewalDate": "2026-02-09",
"renewalDateUpdatedBy": "RENEWAL_DATE_ORGANIZATION_LEVEL",
"billingStartDate": "2026-02-09",
"billingEndDate": "2028-02-09",
"procurementMethod": "Inventory Order - #c853d81c-ba0b-4027-a394-d5586b61608c",
"returnOrder": {
"id": "371da231-5878-45b1-80a3-9113f8795c29",
"status": "PENDING",
"createdAt": "2023-11-07T05:31:56Z",
"returnOrderItemId": "371da231-5878-45b1-80a3-9113f8795c29",
"returnOrderItemStatus": "PENDING",
"retrievalMethod": {
"type": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "REQUESTED",
"inboundTrackingCode": "1Z999AA10123456784",
"inboundTrackingLink": "<string>",
"updatedAt": "2023-11-07T05:31:56Z"
}
},
"assignedTo": {
"id": "371da231-5878-45b1-80a3-9113f8795c29",
"type": "PERSON",
"label": "jane@example.com",
"assignedAt": "2023-11-07T05:31:56Z"
},
"pricing": {
"regionCode": "<string>",
"priceOption": "<string>",
"price": 123,
"currencyCode": "<string>",
"discountedPrice": 123,
"discountPercentage": 123
},
"description": "Custom inventory description",
"netsuiteInvoiceId": "INV-123456",
"holdStartDate": "2023-12-25",
"unlockDate": "2023-12-25",
"itadRequested": true,
"appleBusiness": {
"assignmentStatus": "ASSIGNED",
"nextSyncTimestamp": "2026-07-02T02:00:00Z",
"lastSyncTimestamp": "2026-07-01T12:00:00Z"
}
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}{
"errors": [
{
"detail": "Invalid request",
"source": "request"
}
]
}Authorizations
Prefix the value with "ApiKey" to indicate the custom authorization type
Path Parameters
Body
Request body for updating inventory details
IMEI values associated with the inventory item (mobile devices).
Allowed values:
- `UNAVAILABLE`, only applies to inventory assigned to an office.
- `AVAILABLE`, only applies to inventory assigned to an office.
- `DEPLOYED`, only applies to inventory assigned to a person.
- `ARCHIVED`, applies to inventory assigned to a person or an office.
ARCHIVED, DEPLOYED, UNAVAILABLE, AVAILABLE "ARCHIVED"
Reason for the deployment change.
Allowed values vary based on `deployStatus`:
- For `UNAVAILABLE`, valid reasons are [AWAITING_INFORMATION, DATA_HOLD, LOCKED_APPLE_ACTIVATION, LOCKED_FMD_REPORTED_LOST_STOLEN, LOCKED_MDM, LOCKED_PIN, REQUIRES_REPAIR, OUT_FOR_REPAIR].
- For `ARCHIVED`, valid reasons are [GIFTED_BY_EMPLOYER, LOST_BY_WORKER, BOUGHT_OUT, PERSONAL_DEVICE, END_OF_USEFUL_LIFE_DESTROYED, END_OF_USEFUL_LIFE_DONATED, DECOMMISSIONED_BY_EMPLOYER].
- For `AVAILABLE`, reason must be null.
- For `DEPLOYED`, reason must be null.
GIFTED_BY_EMPLOYER, LOST_BY_WORKER, BOUGHT_OUT, PERSONAL_DEVICE, END_OF_USEFUL_LIFE_DESTROYED, END_OF_USEFUL_LIFE_DONATED, DECOMMISSIONED_BY_EMPLOYER, AWAITING_INFORMATION, DATA_HOLD, LOCKED_APPLE_ACTIVATION, LOCKED_FMD_REPORTED_LOST_STOLEN, LOCKED_MDM, LOCKED_PIN, REQUIRES_REPAIR, OUT_FOR_REPAIR "GIFTED_BY_EMPLOYER"
Update the assignment of the inventory
Show child attributes
Show child attributes
Condition of the inventory item.
NEW, USED "NEW"
Renewal date for the inventory item. Editable when inventory is customer-supplied OR Firstbase-purchased non-subscription.
"2027-01-15"
Serial number. Editable when inventory is customer-supplied OR Firstbase-purchased non-subscription AND assigned to a person/office AND not in return progress. Must be unique within the organization.
"SN-ABC-123"
Free-text description. Editable only for generic SKUs (customer-supplied) AND assigned to person/office AND not in return progress.
"Refurbished MacBook Pro 14\""
Vendor code (brand). Editable only for generic SKUs (customer-supplied) AND assigned to person/office AND not in return progress. Must be paired with vendorSku.
"APPLE"
Vendor SKU (model number). Editable only for generic SKUs (customer-supplied) AND assigned to person/office AND not in return progress. Must be paired with vendorCode.
"MBP14-M3-512"
Response
Inventory updated successfully
A single inventory item (piece of equipment) belonging to the organization
Unique identifier for this inventory item
"ecb7e933-de1e-9830-b180-b25d1d0d296e"
The SKU (product variant) ID this inventory item is associated with
"203a5df2-423a-43a9-bb19-1ccaf3434b91"
IMEI values associated with the inventory item (mobile devices).
Current lifecycle state of the inventory item. DEPLOYED = assigned to a person; AVAILABLE = in a warehouse ready to ship; ARCHIVED = permanently decommissioned; UNAVAILABLE = in warehouse but not ready to ship; AWAITING_ARRIVAL = in transit to a warehouse.
ARCHIVED, AVAILABLE, AWAITING_ARRIVAL, DEPLOYED, ON_HOLD, UNAVAILABLE "ARCHIVED"
Physical condition of the item (NEW or USED)
NEW, USED_LIKE_NEW, USED_GOOD, USED_FAIR, USED, USED_POOR, UNUSABLE "NEW"
Category code of the SKU (e.g. COMPUTER, MONITOR, HEADSET)
"TSHIRT"
Human-readable category name for the SKU
"T-shirt"
Display title of the SKU (product variant name)
"T-shirt White - 5XL"
Vendor/brand code for the SKU
"AWESOME_MERCHANDISE"
Vendor-specific SKU or model identifier
"TSHRT_5XL_WHITE"
Timestamp when this inventory item was created in Firstbase
"2023-02-09T00:00:00"
Timestamp when this inventory item was last updated
"2023-03-02T17:39:01.650027"
List of key-value tags attached to this inventory item for organization and filtering.
Show child attributes
Show child attributes
Hardware serial number of the device; null for non-serialized items
"25f2e6ea9a"
Reason code explaining why the item is in its current deployStatus. Required when transitioning to UNAVAILABLE or ARCHIVED; null when DEPLOYED or AVAILABLE.
ASSIGNED_TO_ADMIN, AWAITING_INFORMATION, BOUGHT_OUT, DATA_HOLD, DECOMMISSIONED_BY_EMPLOYER, END_OF_USEFUL_LIFE_DESTROYED, END_OF_USEFUL_LIFE_DONATED, PENDING_FULFILLMENT, GIFTED_BY_EMPLOYER, GIFTED_BY_FIRSTBASE, IN_TRANSIT, LOCKED_APPLE_ACTIVATION, LOCKED_FMD_REPORTED_LOST_STOLEN, LOCKED_MDM, LOCKED_PIN, LOST_BY_FIRSTBASE, LOST_IN_TRANSIT, LOST_BY_WORKER, MARKED_FOR_DESTRUCTION, NA, NEVER_RECEIVED_BY_WORKER, OTHER, OUT_FOR_DESTRUCTION, OUT_FOR_REPAIR, PENDING_BUY_OUT, RECYCLING_REQUESTED, REQUIRES_CLEANING, REQUIRES_REPAIR, RETURN_IN_PROGRESS, SENT_TO_OFFICE, STOLEN, UNRESPONSIVE_WORKER, UNSUPPORTED_REGION, PERSONAL_DEVICE, PENDING_HOLD_RELEASE "LOST_BY_WORKER"
Date when this item is scheduled for renewal or replacement
"2026-02-09"
Who or what last set the renewalDate (e.g. organization policy vs. manual override)
RENEWAL_DATE_ORGANIZATION_LEVEL, RENEWAL_DATE_ORGANIZATION_CATEGORY_LEVEL, RENEWAL_DATE_MANUALLY_UPDATED, CLEAR_RENEWAL_DATE_MANUALLY_SET "RENEWAL_DATE_ORGANIZATION_LEVEL"
Date when billing began for this inventory item
"2026-02-09"
Date when billing ended or is scheduled to end for this inventory item
"2028-02-09"
Human-readable label indicating how this item was procured (e.g. via an inventory order ID)
"Inventory Order - #c853d81c-ba0b-4027-a394-d5586b61608c"
Details of the return order associated with this inventory item, if a return has been initiated.
Show child attributes
Show child attributes
Information about the person this inventory item is currently assigned to, if applicable.
Show child attributes
Show child attributes
Pricing details
Show child attributes
Show child attributes
Custom description for the inventory item
"Custom inventory description"
NetSuite invoice ID for Firstbase-supplied inventory
"INV-123456"
Date when the machine retention hold started (set at warehouse receive). Null when no hold is active.
Date when the machine retention hold expires (holdStartDate + holdPeriodDays). Null when no hold is active.
Whether ITAD was requested for this item. Copied from the return order item at hold-stamp time.
Apple Business Manager assignment for serialized Apple inventory. Omitted for non-Apple or non-serialized items.
Show child attributes
Show child attributes