{"openapi":"3.1.0","info":{"title":"Firstbase API Specification Beta","description":"Integration endpoints for Firstbase","version":"0.1.0"},"servers":[{"url":"/","description":"Default"}],"security":[{"ApiKey":[]}],"tags":[{"name":"Inventory Orders","description":"Create and manage inventory orders"},{"name":"Shipment Notices V1","description":"Query shipment notice orders (V1: package items expose `inventories` list)"},{"name":"Packages","description":""},{"name":"Categories","description":"Query available categories for asset creation"},{"name":"Catalog","description":""},{"name":"New Joiners","description":"New joiner provisioning pipeline for the organization"},{"name":"Orders","description":""},{"name":"People","description":"Manage the users of Firstbase for your organization. API follows the SCIM standard.","externalDocs":{"url":"https://scim.cloud/"}},{"name":"People — Lifecycle","description":"Offboard and reactivate users."},{"name":"Assets","description":"Manage inventory assets"},{"name":"Regions V1","description":"Query regions (V1)"},{"name":"Warehouses V1","description":"Query warehouses (V1)"},{"name":"Shipment Notices","description":"DEPRECATED: returns one serial number per package item. Use /api/v1/shipment-notices for the full inventories list."},{"name":"Brands","description":"Query available brands for asset creation"},{"name":"Inventory","description":""},{"name":"Replacements","description":"Create and manage equipment replacements"},{"name":"Offices","description":"Manage and query office locations for the authenticated organization"},{"name":"Returns","description":"Return and Replacements"}],"paths":{"/scim/v2/Users/{id}":{"get":{"tags":["People"],"summary":"Get a Firstbase person by their SCIM ID","description":"Retrieves a person's SCIM representation by their internal Firstbase ID. Use the `attributes` or `excludedAttributes` query parameters to control which SCIM fields are included in the response.","operationId":"getUserById","parameters":[{"name":"id","in":"path","description":"Unique id of the user","required":true,"schema":{"type":"string"}},{"name":"attributes","in":"query","description":"Comma-separated SCIM defined attributes to be returned. Required attributes are always returned","required":false,"schema":{"type":"string"}},{"name":"excludedAttributes","in":"query","description":"Comma-separated SCIM defined attributes to be excluded. Required attributes cannot be excluded","required":false,"schema":{"type":"string"}}],"responses":{"404":{"description":"Unable to find user","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"404":{"summary":"User not found","description":"404","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found","status":"404"}}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"User has been found","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UserSchema"}}}}}},"put":{"tags":["People"],"summary":"Replace a Firstbase person's profile via SCIM (full update)","description":"Performs a full replacement (PUT) of a person's SCIM attributes. All writable fields in the request body overwrite the existing values. Used by identity providers (IdPs) to keep person data in sync. Returns 409 if the updated `userName` conflicts with another existing user.","operationId":"updateUser","parameters":[{"name":"attributes","in":"query","description":"Comma-separated SCIM defined attributes to be returned. Required attributes are always returned","required":false,"schema":{"type":"string"}},{"name":"excludedAttributes","in":"query","description":"Comma-separated SCIM defined attributes to be excluded. Required attributes cannot be excluded","required":false,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UserSchema"}}},"required":true},"responses":{"404":{"description":"Unable to find person, organization or package","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"404":{"summary":"User not found","description":"404","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found","status":"404"}}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Unable to update user due to conflict","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"409":{"summary":"A user with this userName already exists","description":"409","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource already exists","scimType":"uniqueness","status":"409"}}}}}},"200":{"description":"User has been updated","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UserSchema"}}}}}},"delete":{"tags":["People"],"summary":"Delete a user from Firstbase","description":"Deleting a User will start the Offboarding process for the user. This is a SOFT delete, in which the user will still have access to the Firstbase platform until offboarding has completed","operationId":"deleteUser","parameters":[{"name":"id","in":"path","description":"Unique id of the user","required":true,"schema":{"type":"string"}},{"name":"addressValidationNeeded","in":"query","description":"When true (default), the user must confirm their shipping address before the return is fulfilled. Set to false to skip address confirmation and proceed with offboarding immediately.","required":false,"schema":{"type":"boolean"}}],"responses":{"404":{"description":"Unable to find user","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"404":{"summary":"User not found","description":"404","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found","status":"404"}}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"User has been deleted and offboarding has started","content":{"application/scim+json":{}}}}}},"/scim/v2/Users":{"get":{"tags":["People"],"summary":"List people in the organization via SCIM","description":"Returns a paginated SCIM ListResponse of people in the caller's organization. Filter by email address or name using SCIM filter expressions. Maximum of 50 users per page.","operationId":"listUsers","parameters":[{"name":"filter","in":"query","description":"Fetch user with a given name or email address using SCIM operators \n\n Examples: \n\n emails.value eq \"test@email.com\" \n\n name.givenName eq \"James\" and name.familyName eq \"Bond\"","schema":{"type":"string"}},{"name":"startIndex","in":"query","description":"The 1-based start index of the first user to be returned","schema":{"type":"integer"}},{"name":"count","in":"query","description":"The number of users to be returned. A maximum of 50 users will be returned in a page.","schema":{"type":"integer"}},{"name":"attributes","in":"query","description":"Comma-separated SCIM defined attributes to be returned. Required attributes are always returned","schema":{"type":"string"}},{"name":"excludedAttributes","in":"query","description":"Comma-separated SCIM defined attributes to be excluded. Required attributes cannot be excluded","schema":{"type":"string"}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"List of users","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UsersSchema"}}}}}},"post":{"tags":["People"],"summary":"Create a new person (employee) in Firstbase via SCIM","description":"Creates a new person record in Firstbase using the SCIM 2.0 protocol. Triggers automatic equipment ordering if the person is assigned to an active package. The `userName` field must be a unique email address. Returns 409 if a user with the same `userName` already exists.","operationId":"createUser","parameters":[{"name":"attributes","in":"query","description":"Comma-separated SCIM defined attributes to be returned. Required attributes are always returned","required":false,"schema":{"type":"string"}},{"name":"excludedAttributes","in":"query","description":"Comma-separated SCIM defined attributes to be excluded. Required attributes cannot be excluded","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UserSchema"}}},"required":true},"responses":{"404":{"description":"Unable to find organization or package","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"404":{"summary":"User not found","description":"404","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found","status":"404"}}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Unable to create user due to conflict","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/ErrorSchema"},"examples":{"409":{"summary":"A user with this userName already exists","description":"409","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"detail":"Resource already exists","scimType":"uniqueness","status":"409"}}}}}},"201":{"description":"User has been created","content":{"application/scim+json":{"schema":{"$ref":"#/components/schemas/UserSchema"}}}}}}},"/scim/v2/Users/csv":{"post":{"tags":["People"],"summary":"Bulk upsert users from CSV","description":"Parses the CSV file and forwards it as a SCIM Bulk request to create and/or update users.\n\nExpected CSV columns (header row): id, forename, surname, email, secondary_email, package_slug, address_line_1, addressLine2, state/region, city_code, country_code, postal_code, phone_number, send_activation_email, cpf_number.\n\nNotes: \n- id: optional UUID. If present, an update (PUT) is generated; if absent, a create (POST) with a bulkId is generated.\n- package_slug: optional; when present and resolvable it is mapped to a packageId.\n- send_activation_email: true/false/yes/no/null (case-insensitive).\n- File must be uploaded as multipart form-data with field name 'file'.- CPF number is mandatory for Brazilian users.","operationId":"bulkUpsertUsersFromCsv","parameters":[{"name":"file","in":"query","description":"CSV file containing users to upsert. Columns should match the Firstbase CSV template.","required":true,"schema":{"type":"string","format":"binary"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object"},"examples":{"People CSV template":{"summary":"Upload as form-data field 'file'","description":"Example CSV content for the 'file' field.","value":"\n                            id,forename,surname,email,secondary_email,package_slug,address_line_1,addressLine2,state/region,city_code,country_code,postal_code,phone_number,send_activation_email,cpf_number\n                            55907ba0-6ee7-3c6c-00a9-8becwb9k83dk,Name,ExampleSurname,email@example.com,example-optional-secondary-email@email.com,developer-a,Test address line 1,Test address line 2,test state,TN,US,37076,6155555555,YES,87425365821\n                            "}}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Bulk operation completed","content":{"application/scim+json":{"schema":{"type":"string"}}}}}}},"/scim/v2/Bulk":{"post":{"tags":["People"],"summary":"SCIM Bulk operations","description":"Performs bulk operations using the SCIM protocol as defined by RFC 7644.","operationId":"scimBulkOperations","requestBody":{"content":{"application/scim+json":{"schema":{"type":"string"},"examples":{"BulkCreateUpdateUsers":{"summary":"Create a user and update an existing user","description":"SCIM Bulk request that creates a new user and updates an existing one.","value":{"schemas":["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],"failOnErrors":1,"Operations":[{"bulkId":"bulk-test","method":"POST","path":"/Users","data":{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:firstbase:1.0:User"],"userName":"testa@example.com","name":{"givenName":"Name","familyName":"ExampleSurname"},"emails":[{"value":"testa@example.com","primary":true},{"value":"testb@email.com","primary":false}],"addresses":[{"type":"home","primary":true,"country":"US","streetAddress":"Test address","postalCode":"37076","region":"test state","locality":"TN"}],"id":"55907ba0-6ee8-4c6c-90a9-8aeccb9b82dc","phoneNumbers":[{"value":"6155555555","primary":true}],"urn:ietf:params:scim:schemas:extension:firstbase:1.0:User":{"packageId":"d41ebe30-279f-41cd-8ag5-7257854d82e5","skipUserActivation":true,"cpfNumber":"87452365895"}}},{"method":"PUT","path":"/Users/4599d8bb-b6df-4ed2-9ad2-6907f8b1fa03","data":{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:firstbase:1.0:User"],"userName":"dev+admin@firstbasedev.com","name":{"givenName":"Test Given Name","familyName":"Test familyName"},"emails":[{"value":"test+swaggera@firstbasedev.com","primary":true},{"value":"test+swaggerb@firstbasedev.com","primary":false}],"addresses":[{"type":"home","primary":true,"country":"US","streetAddress":"Test address ","postalCode":"37076","region":"test state","locality":"TN"}],"id":"4599d8bb-b6df-4ed2-9ad2-6907f8b1fa03","phoneNumbers":[{"value":"6155555555","primary":true}],"urn:ietf:params:scim:schemas:extension:firstbase:1.0:User":{"packageId":"d82ebe36-299f-40ce-8af7-7157853d80d9","skipUserActivation":true,"cpfNumber":"87452365895"}}}]}}}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Bulk operation completed","content":{"application/scim+json":{"schema":{"type":"string"}}}}}}},"/api/v1/shipment-notices":{"get":{"tags":["Shipment Notices V1"],"summary":"List shipment notice orders for the authenticated organization (V1)","description":"Returns a paginated list of shipment notice orders. V1 exposes a full `inventories` list per package item, replacing the single serial-number field in the legacy endpoint. Supports filtering by status, warehouse, and date range.","operationId":"listShipmentNoticesV1","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":100},"example":100},{"name":"status","in":"query","description":"Filter by shipment notice order statuses","required":false,"schema":{"type":"array","description":"Filter by shipment notice order statuses","items":{"type":"string","description":"Filter by shipment notice order statuses","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","NOT_COMPLETED","CANCELLED"]}}},{"name":"condition","in":"query","description":"Filter by shipment notice order conditions","required":false,"schema":{"type":"array","description":"Filter by shipment notice order conditions","items":{"type":"string","description":"Filter by shipment notice order conditions","enum":["NEW","USED"]}}},{"name":"source","in":"query","description":"Filter by source types","required":false,"schema":{"type":"array","description":"Filter by source types","items":{"type":"string","description":"Filter by source types","enum":["SUPPLIER","OFFICE"]}}},{"name":"shipToWarehouse","in":"query","description":"Filter by destination warehouse IDs","required":false,"schema":{"type":"array","description":"Filter by destination warehouse IDs","items":{"type":"string","format":"uuid","description":"Filter by destination warehouse IDs"}}},{"name":"brand","in":"query","description":"Filter by vendor / brand codes","required":false,"schema":{"type":"array","description":"Filter by vendor / brand codes","example":"APPLE","items":{"type":"string","description":"Filter by vendor / brand codes","example":"APPLE"}},"example":"APPLE"},{"name":"category","in":"query","description":"Filter by category codes","required":false,"schema":{"type":"array","description":"Filter by category codes","example":"COMPUTER","items":{"type":"string","description":"Filter by category codes","example":"COMPUTER"}},"example":"COMPUTER"},{"name":"poNumber","in":"query","description":"Filter by purchase order numbers","required":false,"schema":{"type":"array","description":"Filter by purchase order numbers","items":{"type":"string","description":"Filter by purchase order numbers"}}},{"name":"vendorSku","in":"query","description":"Filter by vendor SKUs","required":false,"schema":{"type":"array","description":"Filter by vendor SKUs","items":{"type":"string","description":"Filter by vendor SKUs"}}},{"name":"skuId","in":"query","description":"Filter by SKU IDs","required":false,"schema":{"type":"array","description":"Filter by SKU IDs","items":{"type":"string","format":"uuid","description":"Filter by SKU IDs"}}},{"name":"serialNumber","in":"query","description":"Filter by serial numbers of received inventory items","required":false,"schema":{"type":"array","description":"Filter by serial numbers of received inventory items","items":{"type":"string","description":"Filter by serial numbers of received inventory items"}}},{"name":"orderDateFrom","in":"query","description":"Order date range start (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Order date range start (ISO-8601)","example":"2024-01-01"},"example":"2024-01-01"},{"name":"orderDateTo","in":"query","description":"Order date range end (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Order date range end (ISO-8601)","example":"2024-12-31"},"example":"2024-12-31"},{"name":"sortBy","in":"query","description":"Sort field (createdAt, updatedAt, warehouse, status, submittedBy)","required":false,"schema":{"type":"string","description":"Sort field (createdAt, updatedAt, warehouse, status, submittedBy)","example":"createdAt"},"example":"createdAt"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"DESC"},"example":"DESC"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid filter or pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of shipment notice orders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentNoticeOrderResponseV1"}}}}},"403":{"description":"Feature not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}},"post":{"tags":["Shipment Notices V1"],"summary":"Create a shipment notice","description":"Creates a new shipment notice order. Identify the source as SUPPLIER (with purchase_order_number) or OFFICE. Each shipment contains items identified by sku_id with a quantity.","operationId":"createShipmentNotice","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShipmentNoticeRequest"}}},"required":true},"responses":{"404":{"description":"Warehouse, office, or SKU not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — validation error or invalid input. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Shipment notice created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNoticeResponse"}}}},"403":{"description":"Forbidden — feature flag is disabled or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/returns":{"get":{"tags":["Returns"],"summary":"List all returns","description":"Returns a paginated list of return orders. Each return includes 4 retrieval method types (PL, RETURN_KIT, INBOUND, NOT_MAPPED) with items grouped by method. Empty arrays indicate no items use that method.","operationId":"listReturns","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1,"minimum":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":10,"maximum":500},"example":10},{"name":"personIDs","in":"query","description":"The list of persons that will be returned","required":false,"schema":{"type":"array","description":"The list of persons that will be returned","items":{"type":"string","format":"uuid","description":"The list of persons that will be returned"}}},{"name":"includeShipment","in":"query","description":"Include shipment data in the response","required":false,"schema":{"type":"boolean","description":"Include shipment data in the response"}},{"name":"startDate","in":"query","description":"UTC Date-time to filter orders created after (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter orders created after (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"endDate","in":"query","description":"UTC Date-time to filter orders created before (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter orders created before (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"status","in":"query","description":"Filter by the return order's status.","required":false,"schema":{"type":"array","description":"Filter by the return order's status.","enum":["PENDING","PROCESSING","COMPLETED","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED"],"items":{"type":"string","description":"Filter by the return order's status.","enum":["PENDING","PROCESSING","COMPLETED","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED","PENDING","PROCESSING","COMPLETED","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED"]}}},{"name":"returnKitStatus","in":"query","description":"Filter by retrieval method (return kit) statuses.","required":false,"schema":{"type":"array","description":"Filter by retrieval method (return kit) statuses.","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"],"items":{"type":"string","description":"Filter by retrieval method (return kit) statuses.","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP","REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"]}}},{"name":"submittedBy","in":"query","description":"Filter by person IDs who submitted the return","required":false,"schema":{"type":"array","description":"Filter by person IDs who submitted the return","items":{"type":"string","format":"uuid","description":"Filter by person IDs who submitted the return"}}},{"name":"country","in":"query","description":"Filter by shipping address country codes","required":false,"schema":{"type":"array","description":"Filter by shipping address country codes","items":{"type":"string","description":"Filter by shipping address country codes"}}},{"name":"officeId","in":"query","description":"Filter by office IDs (order's owning office)","required":false,"schema":{"type":"array","description":"Filter by office IDs (order's owning office)","items":{"type":"string","format":"uuid","description":"Filter by office IDs (order's owning office)"}}},{"name":"vendorSku","in":"query","description":"Filter by vendor SKUs","required":false,"schema":{"type":"array","description":"Filter by vendor SKUs","items":{"type":"string","description":"Filter by vendor SKUs"}}},{"name":"skuId","in":"query","description":"Filter by SKU IDs","required":false,"schema":{"type":"array","description":"Filter by SKU IDs","items":{"type":"string","format":"uuid","description":"Filter by SKU IDs"}}},{"name":"serialNumber","in":"query","description":"Filter by inventory serial numbers","required":false,"schema":{"type":"array","description":"Filter by inventory serial numbers","items":{"type":"string","description":"Filter by inventory serial numbers"}}},{"name":"deliveryLocation","in":"query","description":"Filter by the return's delivery location (corresponds to the FE 'Delivery location' multi-select on the Returns page). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.","required":false,"schema":{"type":"array","description":"Filter by the return's delivery location (corresponds to the FE 'Delivery location' multi-select on the Returns page). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.","enum":["FIRSTBASE","OFFICE","MULTIPLE"],"items":{"type":"string","description":"Filter by the return's delivery location (corresponds to the FE 'Delivery location' multi-select on the Returns page). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.","enum":["OFFICE","FIRSTBASE","MULTIPLE","FIRSTBASE","OFFICE","MULTIPLE"]}}},{"name":"sortBy","in":"query","description":"Field to sort by (createdAt, updatedAt, country, deliveryLocation, status, person)","required":false,"schema":{"type":"string","description":"Field to sort by (createdAt, updatedAt, country, deliveryLocation, status, person)","example":"createdAt"},"example":"createdAt"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"DESC"},"example":"DESC"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of return orders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReturnOrderInfo"}}}}}}},"post":{"tags":["Returns"],"summary":"Create a return","description":"Creates a new return order for a person. Items can be identified by inventoryId or serialNumber. If officeId is provided, items are returned to the office (returnMethod forced to SHIPMENT). Otherwise items are returned to the Firstbase warehouse.","operationId":"createReturn","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReturnRequest"}}},"required":true},"responses":{"404":{"description":"Person or inventory not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Return order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnOrderInfo"}}}}}}},"/api/returns":{"get":{"tags":["Returns"],"summary":"List all returns","description":"Returns a paginated list of return orders. Each return includes 4 retrieval method types (PL, RETURN_KIT, INBOUND, NOT_MAPPED) with items grouped by method. Empty arrays indicate no items use that method.","operationId":"listReturns_1","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1,"minimum":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":10,"maximum":500},"example":10},{"name":"personIDs","in":"query","description":"The list of persons that will be returned","required":false,"schema":{"type":"array","description":"The list of persons that will be returned","items":{"type":"string","format":"uuid","description":"The list of persons that will be returned"}}},{"name":"includeShipment","in":"query","description":"Include shipment data in the response","required":false,"schema":{"type":"boolean","description":"Include shipment data in the response"}},{"name":"startDate","in":"query","description":"UTC Date-time to filter orders created after (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter orders created after (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"endDate","in":"query","description":"UTC Date-time to filter orders created before (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter orders created before (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"status","in":"query","description":"Filter by the return order's status.","required":false,"schema":{"type":"array","description":"Filter by the return order's status.","enum":["PENDING","PROCESSING","COMPLETED","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED"],"items":{"type":"string","description":"Filter by the return order's status.","enum":["PENDING","PROCESSING","COMPLETED","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED","PENDING","PROCESSING","COMPLETED","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED"]}}},{"name":"returnKitStatus","in":"query","description":"Filter by retrieval method (return kit) statuses.","required":false,"schema":{"type":"array","description":"Filter by retrieval method (return kit) statuses.","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"],"items":{"type":"string","description":"Filter by retrieval method (return kit) statuses.","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP","REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"]}}},{"name":"submittedBy","in":"query","description":"Filter by person IDs who submitted the return","required":false,"schema":{"type":"array","description":"Filter by person IDs who submitted the return","items":{"type":"string","format":"uuid","description":"Filter by person IDs who submitted the return"}}},{"name":"country","in":"query","description":"Filter by shipping address country codes","required":false,"schema":{"type":"array","description":"Filter by shipping address country codes","items":{"type":"string","description":"Filter by shipping address country codes"}}},{"name":"officeId","in":"query","description":"Filter by office IDs (order's owning office)","required":false,"schema":{"type":"array","description":"Filter by office IDs (order's owning office)","items":{"type":"string","format":"uuid","description":"Filter by office IDs (order's owning office)"}}},{"name":"vendorSku","in":"query","description":"Filter by vendor SKUs","required":false,"schema":{"type":"array","description":"Filter by vendor SKUs","items":{"type":"string","description":"Filter by vendor SKUs"}}},{"name":"skuId","in":"query","description":"Filter by SKU IDs","required":false,"schema":{"type":"array","description":"Filter by SKU IDs","items":{"type":"string","format":"uuid","description":"Filter by SKU IDs"}}},{"name":"serialNumber","in":"query","description":"Filter by inventory serial numbers","required":false,"schema":{"type":"array","description":"Filter by inventory serial numbers","items":{"type":"string","description":"Filter by inventory serial numbers"}}},{"name":"deliveryLocation","in":"query","description":"Filter by the return's delivery location (corresponds to the FE 'Delivery location' multi-select on the Returns page). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.","required":false,"schema":{"type":"array","description":"Filter by the return's delivery location (corresponds to the FE 'Delivery location' multi-select on the Returns page). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.","enum":["FIRSTBASE","OFFICE","MULTIPLE"],"items":{"type":"string","description":"Filter by the return's delivery location (corresponds to the FE 'Delivery location' multi-select on the Returns page). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.","enum":["OFFICE","FIRSTBASE","MULTIPLE","FIRSTBASE","OFFICE","MULTIPLE"]}}},{"name":"sortBy","in":"query","description":"Field to sort by (createdAt, updatedAt, country, deliveryLocation, status, person)","required":false,"schema":{"type":"string","description":"Field to sort by (createdAt, updatedAt, country, deliveryLocation, status, person)","example":"createdAt"},"example":"createdAt"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"DESC"},"example":"DESC"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of return orders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReturnOrderInfo"}}}}}}},"post":{"tags":["Returns"],"summary":"Create a return","description":"Creates a new return order for a person. Items can be identified by inventoryId or serialNumber. If officeId is provided, items are returned to the office (returnMethod forced to SHIPMENT). Otherwise items are returned to the Firstbase warehouse.","operationId":"createReturn_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReturnRequest"}}},"required":true},"responses":{"404":{"description":"Person or inventory not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Return order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnOrderInfo"}}}}}}},"/api/replacements":{"get":{"tags":["Replacements"],"summary":"List all replacements in paginated result","description":"Returns a paginated list of replacement orders for the organization. A replacement is created when a defective or lost device needs to be swapped for a new one.","operationId":"listReplacements","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":100},"example":100},{"name":"replacementOrderStatus","in":"query","description":"Filter by replacement order status (calculated from order and return statuses).","required":false,"schema":{"type":"array","description":"Filter by replacement order status (calculated from order and return statuses).","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","CANCELLED"],"items":{"type":"string","description":"Filter by replacement order status (calculated from order and return statuses).","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","CANCELLED","SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","CANCELLED"]}}},{"name":"country","in":"query","description":"Filter by country codes","required":false,"schema":{"type":"array","description":"Filter by country codes","items":{"type":"string","description":"Filter by country codes"}}},{"name":"submittedBy","in":"query","description":"Filter by person IDs who submitted the replacement","required":false,"schema":{"type":"array","description":"Filter by person IDs who submitted the replacement","items":{"type":"string","format":"uuid","description":"Filter by person IDs who submitted the replacement"}}},{"name":"shipmentStatus","in":"query","description":"Filter by the shipment order status of the replacement's linked order.","required":false,"schema":{"type":"array","description":"Filter by the shipment order status of the replacement's linked order.","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","NONE","APPROVED","AWAITING_FULFILLMENT","PENDING","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"items":{"type":"string","description":"Filter by the shipment order status of the replacement's linked order.","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","ACTIVATED","NONE","APPROVED","AWAITING_FULFILLMENT","ACTION_REQUIRED","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED","AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","NONE","APPROVED","AWAITING_FULFILLMENT","PENDING","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"]}}},{"name":"returnKitStatus","in":"query","description":"Filter by retrieval method (return kit) statuses.","required":false,"schema":{"type":"array","description":"Filter by retrieval method (return kit) statuses.","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"],"items":{"type":"string","description":"Filter by retrieval method (return kit) statuses.","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP","REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"]}}},{"name":"vendorSku","in":"query","description":"Filter by vendor SKUs","required":false,"schema":{"type":"array","description":"Filter by vendor SKUs","items":{"type":"string","description":"Filter by vendor SKUs"}}},{"name":"skuId","in":"query","description":"Filter by SKU IDs","required":false,"schema":{"type":"array","description":"Filter by SKU IDs","items":{"type":"string","format":"uuid","description":"Filter by SKU IDs"}}},{"name":"serialNumber","in":"query","description":"Filter by serial numbers","required":false,"schema":{"type":"array","description":"Filter by serial numbers","items":{"type":"string","description":"Filter by serial numbers"}}},{"name":"startDate","in":"query","description":"Filter replacements created after this date (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Filter replacements created after this date (ISO-8601)","example":"2024-01-01"},"example":"2024-01-01"},{"name":"endDate","in":"query","description":"Filter replacements created before this date (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Filter replacements created before this date (ISO-8601)","example":"2024-12-31"},"example":"2024-12-31"},{"name":"sortBy","in":"query","description":"Field to sort by (createdAt, country, person, status)","required":false,"schema":{"type":"string","description":"Field to sort by (createdAt, country, person, status)","example":"createdAt"},"example":"createdAt"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"DESC"},"example":"DESC"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"A paginated list of replacement orders matching the filter criteria.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicAPIGetReplacementResponse"}}}}}}},"post":{"tags":["Replacements"],"summary":"Create a replacement","description":"Creates a replacement consisting of a return order and a new equipment order","operationId":"createReplacement","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReplacementRequest"}}},"required":true},"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Replacement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPICreateReplacementResponse"}}}}}}},"/api/v1/replacements":{"get":{"tags":["Replacements"],"summary":"List all replacements in paginated result","description":"Returns a paginated list of replacement orders for the organization. A replacement is created when a defective or lost device needs to be swapped for a new one.","operationId":"listReplacements_1","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":100},"example":100},{"name":"replacementOrderStatus","in":"query","description":"Filter by replacement order status (calculated from order and return statuses).","required":false,"schema":{"type":"array","description":"Filter by replacement order status (calculated from order and return statuses).","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","CANCELLED"],"items":{"type":"string","description":"Filter by replacement order status (calculated from order and return statuses).","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","CANCELLED","SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","CANCELLED"]}}},{"name":"country","in":"query","description":"Filter by country codes","required":false,"schema":{"type":"array","description":"Filter by country codes","items":{"type":"string","description":"Filter by country codes"}}},{"name":"submittedBy","in":"query","description":"Filter by person IDs who submitted the replacement","required":false,"schema":{"type":"array","description":"Filter by person IDs who submitted the replacement","items":{"type":"string","format":"uuid","description":"Filter by person IDs who submitted the replacement"}}},{"name":"shipmentStatus","in":"query","description":"Filter by the shipment order status of the replacement's linked order.","required":false,"schema":{"type":"array","description":"Filter by the shipment order status of the replacement's linked order.","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","NONE","APPROVED","AWAITING_FULFILLMENT","PENDING","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"items":{"type":"string","description":"Filter by the shipment order status of the replacement's linked order.","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","ACTIVATED","NONE","APPROVED","AWAITING_FULFILLMENT","ACTION_REQUIRED","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED","AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","NONE","APPROVED","AWAITING_FULFILLMENT","PENDING","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"]}}},{"name":"returnKitStatus","in":"query","description":"Filter by retrieval method (return kit) statuses.","required":false,"schema":{"type":"array","description":"Filter by retrieval method (return kit) statuses.","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"],"items":{"type":"string","description":"Filter by retrieval method (return kit) statuses.","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP","REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"]}}},{"name":"vendorSku","in":"query","description":"Filter by vendor SKUs","required":false,"schema":{"type":"array","description":"Filter by vendor SKUs","items":{"type":"string","description":"Filter by vendor SKUs"}}},{"name":"skuId","in":"query","description":"Filter by SKU IDs","required":false,"schema":{"type":"array","description":"Filter by SKU IDs","items":{"type":"string","format":"uuid","description":"Filter by SKU IDs"}}},{"name":"serialNumber","in":"query","description":"Filter by serial numbers","required":false,"schema":{"type":"array","description":"Filter by serial numbers","items":{"type":"string","description":"Filter by serial numbers"}}},{"name":"startDate","in":"query","description":"Filter replacements created after this date (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Filter replacements created after this date (ISO-8601)","example":"2024-01-01"},"example":"2024-01-01"},{"name":"endDate","in":"query","description":"Filter replacements created before this date (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Filter replacements created before this date (ISO-8601)","example":"2024-12-31"},"example":"2024-12-31"},{"name":"sortBy","in":"query","description":"Field to sort by (createdAt, country, person, status)","required":false,"schema":{"type":"string","description":"Field to sort by (createdAt, country, person, status)","example":"createdAt"},"example":"createdAt"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"DESC"},"example":"DESC"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"A paginated list of replacement orders matching the filter criteria.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicAPIGetReplacementResponse"}}}}}}},"post":{"tags":["Replacements"],"summary":"Create a replacement","description":"Creates a replacement consisting of a return order and a new equipment order","operationId":"createReplacement_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReplacementRequest"}}},"required":true},"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Replacement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPICreateReplacementResponse"}}}}}}},"/api/people/{personId}/reactivate":{"post":{"tags":["People — Lifecycle"],"summary":"Reactivate a person.","operationId":"reactivate","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Person not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Validation or business rule error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Person"}}}},"403":{"description":"Contract tier not available or feature flag disabled","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/people/{personId}/reactivate":{"post":{"tags":["People — Lifecycle"],"summary":"Reactivate a person.","operationId":"reactivate_1","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Person not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Validation or business rule error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Person"}}}},"403":{"description":"Contract tier not available or feature flag disabled","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/people/{personId}/offboard":{"post":{"tags":["People — Lifecycle"],"summary":"Offboard a person.","operationId":"offboard","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffboardPersonRequest"}}},"required":true},"responses":{"404":{"description":"Person not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Validation or business rule error. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only for shipment return paths (SHIP_TO_FIRSTBASE, SHIP_TO_OFFICE).","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Person"}}}},"403":{"description":"Contract tier not available or feature flag disabled","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/people/{personId}/offboard":{"post":{"tags":["People — Lifecycle"],"summary":"Offboard a person.","operationId":"offboard_1","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffboardPersonRequest"}}},"required":true},"responses":{"404":{"description":"Person not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Validation or business rule error. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only for shipment return paths (SHIP_TO_FIRSTBASE, SHIP_TO_OFFICE).","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Person"}}}},"403":{"description":"Contract tier not available or feature flag disabled","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/people/{personId}/emails":{"post":{"tags":["People"],"summary":"Send an admin email to a person","description":"Triggers an admin email action for the specified person. The `emailType` determines the action:\n\n- **RESEND_ACTIVATION** — Resends the activation email to a person with INVITED status who has a platform account.\n- **RESEND_OFFBOARDING** — Resends the arrange-return / offboarding email to a person who is currently being offboarded (OFFBOARDING status).\n- **SEND_PLATFORM_INVITE** — Sends a platform access invite email to an ACTIVE person who does not yet have platform access. Creates a platform account and sets the person's status to INVITED.","operationId":"sendPersonEmail","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeopleEmailRequest"}}},"required":true},"responses":{"404":{"description":"Person not found, or feature flag is disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — the person is not eligible for the requested email action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Email sent successfully"},"403":{"description":"Forbidden — missing or invalid API key"}}}},"/api/v1/people/{personId}/emails":{"post":{"tags":["People"],"summary":"Send an admin email to a person","description":"Triggers an admin email action for the specified person. The `emailType` determines the action:\n\n- **RESEND_ACTIVATION** — Resends the activation email to a person with INVITED status who has a platform account.\n- **RESEND_OFFBOARDING** — Resends the arrange-return / offboarding email to a person who is currently being offboarded (OFFBOARDING status).\n- **SEND_PLATFORM_INVITE** — Sends a platform access invite email to an ACTIVE person who does not yet have platform access. Creates a platform account and sets the person's status to INVITED.","operationId":"sendPersonEmail_1","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeopleEmailRequest"}}},"required":true},"responses":{"404":{"description":"Person not found, or feature flag is disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — the person is not eligible for the requested email action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Email sent successfully"},"403":{"description":"Forbidden — missing or invalid API key"}}}},"/api/v1/packages":{"get":{"tags":["Packages"],"summary":"List all equipment packages for the authenticated organization","description":"Returns a paginated list of equipment packages (onboarding bundles) belonging to the caller's organization. Each package contains SKUs and rules that determine what equipment new joiners receive automatically.","operationId":"listPackages","parameters":[{"name":"page","in":"query","description":"Zero-based page index (0..N)","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"size","in":"query","description":"The size of the page to be returned","required":false,"schema":{"type":"integer","default":100,"minimum":1}},{"name":"sort","in":"query","description":"Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.","required":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of packages","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Package"}}}}}}},"post":{"tags":["Packages"],"summary":"Create a new equipment package","description":"Creates a new equipment package (onboarding bundle) for the caller's organization. The package defines which SKUs are automatically ordered when a new joiner is onboarded. Gated by a feature flag; returns 403 when the flag is disabled.","operationId":"createPackage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePackageRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Invalid request — validation error or missing required field"},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"403":{"description":"Feature flag disabled or access denied"},"201":{"description":"Package created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePackageResponse"}}}}}}},"/api/packages":{"get":{"tags":["Packages"],"summary":"List all equipment packages for the authenticated organization","description":"Returns a paginated list of equipment packages (onboarding bundles) belonging to the caller's organization. Each package contains SKUs and rules that determine what equipment new joiners receive automatically.","operationId":"listPackages_1","parameters":[{"name":"page","in":"query","description":"Zero-based page index (0..N)","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"size","in":"query","description":"The size of the page to be returned","required":false,"schema":{"type":"integer","default":100,"minimum":1}},{"name":"sort","in":"query","description":"Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.","required":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of packages","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Package"}}}}}}},"post":{"tags":["Packages"],"summary":"Create a new equipment package","description":"Creates a new equipment package (onboarding bundle) for the caller's organization. The package defines which SKUs are automatically ordered when a new joiner is onboarded. Gated by a feature flag; returns 403 when the flag is disabled.","operationId":"createPackage_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePackageRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Invalid request — validation error or missing required field"},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"403":{"description":"Feature flag disabled or access denied"},"201":{"description":"Package created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePackageResponse"}}}}}}},"/api/v1/orders/{orderId}/decline":{"post":{"tags":["Orders"],"summary":"Decline an order awaiting approval","description":"Rejects an order that is awaiting approval. Transitions AWAITING_APPROVAL → DECLINED. All non-cancelled order items are also set to DECLINED. Sends a decline notification email for person orders.\n\n**Not for cancelling ORDERED or APPROVED orders.** To cancel an active order, use PATCH /api/v1/orders/{orderId} with `{\"status\": \"CANCELLED\"}` instead.","operationId":"declineOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Order is not in AWAITING_APPROVAL status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Order declined successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}}},"/api/orders/{orderId}/decline":{"post":{"tags":["Orders"],"summary":"Decline an order awaiting approval","description":"Rejects an order that is awaiting approval. Transitions AWAITING_APPROVAL → DECLINED. All non-cancelled order items are also set to DECLINED. Sends a decline notification email for person orders.\n\n**Not for cancelling ORDERED or APPROVED orders.** To cancel an active order, use PATCH /api/v1/orders/{orderId} with `{\"status\": \"CANCELLED\"}` instead.","operationId":"declineOrder_1","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Order is not in AWAITING_APPROVAL status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Order declined successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}}},"/api/v1/orders/{orderId}/approve":{"post":{"tags":["Orders"],"summary":"Approve an order","description":"Transitions an order from AWAITING_APPROVAL to APPROVED status. Optionally accepts an approvedByPersonId to record who approved the order. Sends an approval notification email for person orders.","operationId":"approveOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIApproveOrderRequest"}}}},"responses":{"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Order is not in AWAITING_APPROVAL status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Order approved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}}},"/api/orders/{orderId}/approve":{"post":{"tags":["Orders"],"summary":"Approve an order","description":"Transitions an order from AWAITING_APPROVAL to APPROVED status. Optionally accepts an approvedByPersonId to record who approved the order. Sends an approval notification email for person orders.","operationId":"approveOrder_1","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIApproveOrderRequest"}}}},"responses":{"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Order is not in AWAITING_APPROVAL status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Order approved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}}},"/api/v1/orders":{"get":{"tags":["Orders"],"summary":"List all orders for the authenticated organization","description":"Returns a paginated list of orders belonging to the caller's organization. Supports filtering by person, date range, status, and sorting. Results are sorted by creation date ascending by default.","operationId":"getOrders","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":100},"example":100},{"name":"personId","in":"query","description":"The ID of the person to return orders for","required":false,"schema":{"type":"string","format":"uuid","description":"The ID of the person to return orders for","example":"d7d0d906-425f-402f-bde1-39031c67c40b"},"example":"d7d0d906-425f-402f-bde1-39031c67c40b"},{"name":"startDate","in":"query","description":"UTC Date-time to filter orders created after (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter orders created after (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"endDate","in":"query","description":"UTC Date-time to filter orders created before (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter orders created before (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"status","in":"query","description":"Filter by order statuses","required":false,"schema":{"type":"array","description":"Filter by order statuses","items":{"type":"string","description":"Filter by order statuses","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","ACTIVATED","NONE","APPROVED","AWAITING_FULFILLMENT","ACTION_REQUIRED","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"]}}},{"name":"expectedByFrom","in":"query","description":"Filter by earliest expected-by date (requires expectedByTo)","required":false,"schema":{"type":"string","format":"date","description":"Filter by earliest expected-by date (requires expectedByTo)","example":"2024-01-01"},"example":"2024-01-01"},{"name":"expectedByTo","in":"query","description":"Filter by latest expected-by date (requires expectedByFrom)","required":false,"schema":{"type":"string","format":"date","description":"Filter by latest expected-by date (requires expectedByFrom)","example":"2024-12-31"},"example":"2024-12-31"},{"name":"packageSlug","in":"query","description":"Filter by package slug","required":false,"schema":{"type":"array","description":"Filter by package slug","items":{"type":"string","description":"Filter by package slug"}}},{"name":"submittedBy","in":"query","description":"Filter by person IDs who submitted the order","required":false,"schema":{"type":"array","description":"Filter by person IDs who submitted the order","items":{"type":"string","format":"uuid","description":"Filter by person IDs who submitted the order"}}},{"name":"approvedBy","in":"query","description":"Filter by person IDs who approved the order","required":false,"schema":{"type":"array","description":"Filter by person IDs who approved the order","items":{"type":"string","format":"uuid","description":"Filter by person IDs who approved the order"}}},{"name":"country","in":"query","description":"Filter by destination country codes","required":false,"schema":{"type":"array","description":"Filter by destination country codes","items":{"type":"string","description":"Filter by destination country codes"}}},{"name":"recipientType","in":"query","description":"Filter by recipient type (PERSON, OFFICE)","required":false,"schema":{"type":"string","description":"Filter by recipient type (PERSON, OFFICE)","enum":["PERSON","OFFICE"]}},{"name":"deliveryLocation","in":"query","description":"Filter by delivery location type (corresponds to the FE 'Delivery location' toggle on the Orders page, where PERSON is shown to users as 'Employee'). Allowed values: PERSON, OFFICE.","required":false,"schema":{"type":"string","description":"Filter by delivery location type (corresponds to the FE 'Delivery location' toggle on the Orders page, where PERSON is shown to users as 'Employee'). Allowed values: PERSON, OFFICE.","enum":["PERSON","OFFICE","PERSON","OFFICE"]}},{"name":"vendorSku","in":"query","description":"Filter by vendor SKUs","required":false,"schema":{"type":"array","description":"Filter by vendor SKUs","items":{"type":"string","description":"Filter by vendor SKUs"}}},{"name":"skuId","in":"query","description":"Filter by SKU IDs","required":false,"schema":{"type":"array","description":"Filter by SKU IDs","items":{"type":"string","format":"uuid","description":"Filter by SKU IDs"}}},{"name":"serialNumber","in":"query","description":"Filter by serial numbers","required":false,"schema":{"type":"array","description":"Filter by serial numbers","items":{"type":"string","description":"Filter by serial numbers"}}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","description":"Field to sort by","example":"createdAt"},"example":"createdAt"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"DESC"},"example":"DESC"}],"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid filter or pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of orders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}}},"post":{"tags":["Orders"],"summary":"Create a new equipment order for a person or office","description":"Places a new order for one or more SKUs, delivered to either a person or an office. Exactly one of `personId` or `officeId` must be provided. Shipping address is auto-resolved from the recipient when not explicitly supplied. Returns the newly created order, including its ID and initial status.","operationId":"createOrder","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPICreateOrderRequest"}}},"required":true},"responses":{"404":{"description":"Person, office, or SKU not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — validation error, missing required field, or invalid SKU/person/office combination. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPICreateOrderResponse"}}}}}}},"/api/orders":{"get":{"tags":["Orders"],"summary":"List all orders for the authenticated organization","description":"Returns a paginated list of orders belonging to the caller's organization. Supports filtering by person, date range, status, and sorting. Results are sorted by creation date ascending by default.","operationId":"getOrders_1","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":100},"example":100},{"name":"personId","in":"query","description":"The ID of the person to return orders for","required":false,"schema":{"type":"string","format":"uuid","description":"The ID of the person to return orders for","example":"d7d0d906-425f-402f-bde1-39031c67c40b"},"example":"d7d0d906-425f-402f-bde1-39031c67c40b"},{"name":"startDate","in":"query","description":"UTC Date-time to filter orders created after (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter orders created after (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"endDate","in":"query","description":"UTC Date-time to filter orders created before (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter orders created before (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"status","in":"query","description":"Filter by order statuses","required":false,"schema":{"type":"array","description":"Filter by order statuses","items":{"type":"string","description":"Filter by order statuses","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","ACTIVATED","NONE","APPROVED","AWAITING_FULFILLMENT","ACTION_REQUIRED","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"]}}},{"name":"expectedByFrom","in":"query","description":"Filter by earliest expected-by date (requires expectedByTo)","required":false,"schema":{"type":"string","format":"date","description":"Filter by earliest expected-by date (requires expectedByTo)","example":"2024-01-01"},"example":"2024-01-01"},{"name":"expectedByTo","in":"query","description":"Filter by latest expected-by date (requires expectedByFrom)","required":false,"schema":{"type":"string","format":"date","description":"Filter by latest expected-by date (requires expectedByFrom)","example":"2024-12-31"},"example":"2024-12-31"},{"name":"packageSlug","in":"query","description":"Filter by package slug","required":false,"schema":{"type":"array","description":"Filter by package slug","items":{"type":"string","description":"Filter by package slug"}}},{"name":"submittedBy","in":"query","description":"Filter by person IDs who submitted the order","required":false,"schema":{"type":"array","description":"Filter by person IDs who submitted the order","items":{"type":"string","format":"uuid","description":"Filter by person IDs who submitted the order"}}},{"name":"approvedBy","in":"query","description":"Filter by person IDs who approved the order","required":false,"schema":{"type":"array","description":"Filter by person IDs who approved the order","items":{"type":"string","format":"uuid","description":"Filter by person IDs who approved the order"}}},{"name":"country","in":"query","description":"Filter by destination country codes","required":false,"schema":{"type":"array","description":"Filter by destination country codes","items":{"type":"string","description":"Filter by destination country codes"}}},{"name":"recipientType","in":"query","description":"Filter by recipient type (PERSON, OFFICE)","required":false,"schema":{"type":"string","description":"Filter by recipient type (PERSON, OFFICE)","enum":["PERSON","OFFICE"]}},{"name":"deliveryLocation","in":"query","description":"Filter by delivery location type (corresponds to the FE 'Delivery location' toggle on the Orders page, where PERSON is shown to users as 'Employee'). Allowed values: PERSON, OFFICE.","required":false,"schema":{"type":"string","description":"Filter by delivery location type (corresponds to the FE 'Delivery location' toggle on the Orders page, where PERSON is shown to users as 'Employee'). Allowed values: PERSON, OFFICE.","enum":["PERSON","OFFICE","PERSON","OFFICE"]}},{"name":"vendorSku","in":"query","description":"Filter by vendor SKUs","required":false,"schema":{"type":"array","description":"Filter by vendor SKUs","items":{"type":"string","description":"Filter by vendor SKUs"}}},{"name":"skuId","in":"query","description":"Filter by SKU IDs","required":false,"schema":{"type":"array","description":"Filter by SKU IDs","items":{"type":"string","format":"uuid","description":"Filter by SKU IDs"}}},{"name":"serialNumber","in":"query","description":"Filter by serial numbers","required":false,"schema":{"type":"array","description":"Filter by serial numbers","items":{"type":"string","description":"Filter by serial numbers"}}},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","description":"Field to sort by","example":"createdAt"},"example":"createdAt"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"DESC"},"example":"DESC"}],"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid filter or pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of orders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}}},"post":{"tags":["Orders"],"summary":"Create a new equipment order for a person or office","description":"Places a new order for one or more SKUs, delivered to either a person or an office. Exactly one of `personId` or `officeId` must be provided. Shipping address is auto-resolved from the recipient when not explicitly supplied. Returns the newly created order, including its ID and initial status.","operationId":"createOrder_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPICreateOrderRequest"}}},"required":true},"responses":{"404":{"description":"Person, office, or SKU not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — validation error, missing required field, or invalid SKU/person/office combination. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPICreateOrderResponse"}}}}}}},"/api/new-joiners/{personId}/remind":{"post":{"tags":["New Joiners"],"summary":"Send new joiner reminder","description":"Sends a reminder email to the specified new joiner. Optionally records the sender person for audit purposes.","operationId":"sendNewJoinerReminder","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPISendReminderRequest"}}}},"responses":{"404":{"description":"Person or sender not found in the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Reminder sent successfully"}}}},"/api/v1/new-joiners/{personId}/remind":{"post":{"tags":["New Joiners"],"summary":"Send new joiner reminder","description":"Sends a reminder email to the specified new joiner. Optionally records the sender person for audit purposes.","operationId":"sendNewJoinerReminder_1","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPISendReminderRequest"}}}},"responses":{"404":{"description":"Person or sender not found in the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Reminder sent successfully"}}}},"/api/itad/requests":{"get":{"tags":["ITAD"],"summary":"List ITAD requests","description":"Returns a paginated list of ITAD (IT Asset Disposition) requests for the organization. Each request represents a scheduled disposition event for one or more inventory items. Use query parameters to filter by status or date range.","operationId":"listITADRequests","parameters":[{"name":"page","in":"query","description":"Page number (1-based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":25,"maximum":100},"example":25},{"name":"status","in":"query","description":"Filter by request status","required":false,"allowEmptyValue":true,"schema":{"type":"string","enum":["PENDING_DATA_DESTRUCTION","REQUIRES_ACTION","AWAITING_RECHECK","PENDING_SETTLEMENT","COMPLETED","CANCELLED"]}},{"name":"warehouseId","in":"query","description":"Filter by warehouse ID","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"uuid"},"example":"00000000-0000-0000-0000-000000000000"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of ITAD requests","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ITADRequest"}}}}}}},"post":{"tags":["ITAD"],"summary":"Create ITAD requests","description":"Create ITAD requests from a list of inventory IDs. Items are automatically grouped by warehouse, creating one request per warehouse.","operationId":"createITADRequests","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateITADRequestsRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request (invalid inventory IDs, ineligible assets, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"ITAD requests created successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ITADRequest"}}}}}}}},"/api/v1/itad/requests":{"get":{"tags":["ITAD"],"summary":"List ITAD requests","description":"Returns a paginated list of ITAD (IT Asset Disposition) requests for the organization. Each request represents a scheduled disposition event for one or more inventory items. Use query parameters to filter by status or date range.","operationId":"listITADRequests_1","parameters":[{"name":"page","in":"query","description":"Page number (1-based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":25,"maximum":100},"example":25},{"name":"status","in":"query","description":"Filter by request status","required":false,"allowEmptyValue":true,"schema":{"type":"string","enum":["PENDING_DATA_DESTRUCTION","REQUIRES_ACTION","AWAITING_RECHECK","PENDING_SETTLEMENT","COMPLETED","CANCELLED"]}},{"name":"warehouseId","in":"query","description":"Filter by warehouse ID","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"uuid"},"example":"00000000-0000-0000-0000-000000000000"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of ITAD requests","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ITADRequest"}}}}}}},"post":{"tags":["ITAD"],"summary":"Create ITAD requests","description":"Create ITAD requests from a list of inventory IDs. Items are automatically grouped by warehouse, creating one request per warehouse.","operationId":"createITADRequests_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateITADRequestsRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request (invalid inventory IDs, ineligible assets, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"ITAD requests created successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ITADRequest"}}}}}}}},"/api/inventory/{inventoryId}/tags":{"post":{"tags":["Inventory"],"summary":"Add tags to inventory","description":"Adds one or more tags to an inventory item. Tags are key-value labels used to organize and filter inventory. Existing tags with the same key are not replaced — duplicates are ignored.","operationId":"addTagsToInventory","parameters":[{"name":"inventoryId","in":"path","description":"The Inventory ID to add the tags to","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIAddTagsRequest"}}},"required":true},"responses":{"404":{"description":"Inventory not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Tag already exists for the inventory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Tags added successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InventoryTag"}}}}}}}},"/api/v1/inventory/{inventoryId}/tags":{"post":{"tags":["Inventory"],"summary":"Add tags to inventory","description":"Adds one or more tags to an inventory item. Tags are key-value labels used to organize and filter inventory. Existing tags with the same key are not replaced — duplicates are ignored.","operationId":"addTagsToInventory_1","parameters":[{"name":"inventoryId","in":"path","description":"The Inventory ID to add the tags to","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIAddTagsRequest"}}},"required":true},"responses":{"404":{"description":"Inventory not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Tag already exists for the inventory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Tags added successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InventoryTag"}}}}}}}},"/api/v1/inventory-orders":{"get":{"tags":["Inventory Orders"],"summary":"List all inventory orders for the authenticated organization","description":"Returns a paginated list of inventory orders (warehouse stock replenishment requests) for the caller's organization. Supports filtering by status and date range, and sorting by creation date. Each result includes the ordered items and their shipment details.","operationId":"listInventoryOrders","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":100,"maximum":100,"minimum":1},"example":100},{"name":"ids","in":"query","description":"Filter by inventory order IDs","required":false,"schema":{"type":"array","description":"Filter by inventory order IDs","items":{"type":"string","format":"uuid","description":"Filter by inventory order IDs"}}},{"name":"statuses","in":"query","description":"Filter by order statuses (e.g. SUBMITTED, PROCESSING)","required":false,"schema":{"type":"array","description":"Filter by order statuses (e.g. SUBMITTED, PROCESSING)","items":{"type":"string","description":"Filter by order statuses (e.g. SUBMITTED, PROCESSING)","enum":["CANCELLED","COMPLETE","ORDERED","PARTIALLY_RECEIVED","PROCESSING","RECEIVED","SHIPPED","SUBMITTED"]}}},{"name":"warehouseIds","in":"query","description":"Filter by warehouse IDs","required":false,"schema":{"type":"array","description":"Filter by warehouse IDs","items":{"type":"string","format":"uuid","description":"Filter by warehouse IDs"}}},{"name":"categories","in":"query","description":"Filter by product categories (e.g. COMPUTER)","required":false,"schema":{"type":"array","description":"Filter by product categories (e.g. COMPUTER)","items":{"type":"string","description":"Filter by product categories (e.g. COMPUTER)"}}},{"name":"brands","in":"query","description":"Filter by product brands","required":false,"schema":{"type":"array","description":"Filter by product brands","items":{"type":"string","description":"Filter by product brands"}}},{"name":"customerPoNumbers","in":"query","description":"Filter by customer PO numbers","required":false,"schema":{"type":"array","description":"Filter by customer PO numbers","items":{"type":"string","description":"Filter by customer PO numbers"}}},{"name":"friendlyOrderIds","in":"query","description":"Filter by exact friendly order IDs (case-insensitive)","required":false,"schema":{"type":"array","description":"Filter by exact friendly order IDs (case-insensitive)","example":"ORD-000123","items":{"type":"string","description":"Filter by exact friendly order IDs (case-insensitive)","example":"ORD-000123"}},"example":"ORD-000123"},{"name":"submittedBy","in":"query","description":"Filter by person IDs who submitted the order","required":false,"schema":{"type":"array","description":"Filter by person IDs who submitted the order","items":{"type":"string","format":"uuid","description":"Filter by person IDs who submitted the order"}}},{"name":"includeOrdersWithoutSubmitter","in":"query","description":"When true, includes orders without a submitter (system-generated). OR'd with submittedBy if both are provided.","required":false,"schema":{"type":"boolean","description":"When true, includes orders without a submitter (system-generated). OR'd with submittedBy if both are provided."}},{"name":"reasons","in":"query","description":"Filter by order reasons (e.g. ONE_OFF, RESTOCK)","required":false,"schema":{"type":"array","description":"Filter by order reasons (e.g. ONE_OFF, RESTOCK)","items":{"type":"string","description":"Filter by order reasons (e.g. ONE_OFF, RESTOCK)","enum":["ONE_OFF","RESTOCK"]}}},{"name":"createdDateFrom","in":"query","description":"Filter orders created on or after this date (ISO-8601). If provided, createdDateTo must also be provided.","required":false,"schema":{"type":"string","format":"date","description":"Filter orders created on or after this date (ISO-8601). If provided, createdDateTo must also be provided.","example":"2024-01-01"},"example":"2024-01-01"},{"name":"createdDateTo","in":"query","description":"Filter orders created on or before this date (ISO-8601). If provided, createdDateFrom must also be provided.","required":false,"schema":{"type":"string","format":"date","description":"Filter orders created on or before this date (ISO-8601). If provided, createdDateFrom must also be provided.","example":"2024-12-31"},"example":"2024-12-31"},{"name":"expectedShipDateFrom","in":"query","description":"Filter orders with expected ship date on or after this date (ISO-8601). If provided, expectedShipDateTo must also be provided.","required":false,"schema":{"type":"string","format":"date","description":"Filter orders with expected ship date on or after this date (ISO-8601). If provided, expectedShipDateTo must also be provided.","example":"2024-01-01"},"example":"2024-01-01"},{"name":"expectedShipDateTo","in":"query","description":"Filter orders with expected ship date on or before this date (ISO-8601). If provided, expectedShipDateFrom must also be provided.","required":false,"schema":{"type":"string","format":"date","description":"Filter orders with expected ship date on or before this date (ISO-8601). If provided, expectedShipDateFrom must also be provided.","example":"2024-12-31"},"example":"2024-12-31"},{"name":"searchString","in":"query","description":"Search string to filter orders","required":false,"schema":{"type":"string","description":"Search string to filter orders","example":"laptop"},"example":"laptop"},{"name":"vendorSku","in":"query","description":"Filter by SKU vendor SKUs (MPN).","required":false,"schema":{"type":"array","description":"Filter by SKU vendor SKUs (MPN).","items":{"type":"string","description":"Filter by SKU vendor SKUs (MPN)."}}},{"name":"skuId","in":"query","description":"Filter by SKU IDs.","required":false,"schema":{"type":"array","description":"Filter by SKU IDs.","items":{"type":"string","format":"uuid","description":"Filter by SKU IDs."}}},{"name":"serialNumber","in":"query","description":"Filter by inventory serial numbers.","required":false,"schema":{"type":"array","description":"Filter by inventory serial numbers.","items":{"type":"string","description":"Filter by inventory serial numbers."}}},{"name":"sortBy","in":"query","description":"Field to sort by (createdAt, updatedAt, warehouse, status, submittedBy).","required":false,"schema":{"type":"string","description":"Field to sort by (createdAt, updatedAt, warehouse, status, submittedBy).","example":"createdAt"},"example":"createdAt"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC).","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC).","example":"DESC"},"example":"DESC"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid filter or pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of inventory orders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InventoryOrderResponse"}}}}}}},"post":{"tags":["Inventory Orders"],"summary":"Create an inventory order","description":"Creates an inventory order to ship equipment from a supplier or customer to a Firstbase warehouse. Specify the destination warehouse and the items (SKUs with quantities) to be stocked. The created order begins in SUBMITTED status and will be processed by the Firstbase logistics team.","operationId":"createInventoryOrder","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryOrderRequest"}}},"required":true},"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Inventory order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryOrderResponse"}}}}}}},"/api/inventory-orders":{"get":{"tags":["Inventory Orders"],"summary":"List all inventory orders for the authenticated organization","description":"Returns a paginated list of inventory orders (warehouse stock replenishment requests) for the caller's organization. Supports filtering by status and date range, and sorting by creation date. Each result includes the ordered items and their shipment details.","operationId":"listInventoryOrders_1","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":100,"maximum":100,"minimum":1},"example":100},{"name":"ids","in":"query","description":"Filter by inventory order IDs","required":false,"schema":{"type":"array","description":"Filter by inventory order IDs","items":{"type":"string","format":"uuid","description":"Filter by inventory order IDs"}}},{"name":"statuses","in":"query","description":"Filter by order statuses (e.g. SUBMITTED, PROCESSING)","required":false,"schema":{"type":"array","description":"Filter by order statuses (e.g. SUBMITTED, PROCESSING)","items":{"type":"string","description":"Filter by order statuses (e.g. SUBMITTED, PROCESSING)","enum":["CANCELLED","COMPLETE","ORDERED","PARTIALLY_RECEIVED","PROCESSING","RECEIVED","SHIPPED","SUBMITTED"]}}},{"name":"warehouseIds","in":"query","description":"Filter by warehouse IDs","required":false,"schema":{"type":"array","description":"Filter by warehouse IDs","items":{"type":"string","format":"uuid","description":"Filter by warehouse IDs"}}},{"name":"categories","in":"query","description":"Filter by product categories (e.g. COMPUTER)","required":false,"schema":{"type":"array","description":"Filter by product categories (e.g. COMPUTER)","items":{"type":"string","description":"Filter by product categories (e.g. COMPUTER)"}}},{"name":"brands","in":"query","description":"Filter by product brands","required":false,"schema":{"type":"array","description":"Filter by product brands","items":{"type":"string","description":"Filter by product brands"}}},{"name":"customerPoNumbers","in":"query","description":"Filter by customer PO numbers","required":false,"schema":{"type":"array","description":"Filter by customer PO numbers","items":{"type":"string","description":"Filter by customer PO numbers"}}},{"name":"friendlyOrderIds","in":"query","description":"Filter by exact friendly order IDs (case-insensitive)","required":false,"schema":{"type":"array","description":"Filter by exact friendly order IDs (case-insensitive)","example":"ORD-000123","items":{"type":"string","description":"Filter by exact friendly order IDs (case-insensitive)","example":"ORD-000123"}},"example":"ORD-000123"},{"name":"submittedBy","in":"query","description":"Filter by person IDs who submitted the order","required":false,"schema":{"type":"array","description":"Filter by person IDs who submitted the order","items":{"type":"string","format":"uuid","description":"Filter by person IDs who submitted the order"}}},{"name":"includeOrdersWithoutSubmitter","in":"query","description":"When true, includes orders without a submitter (system-generated). OR'd with submittedBy if both are provided.","required":false,"schema":{"type":"boolean","description":"When true, includes orders without a submitter (system-generated). OR'd with submittedBy if both are provided."}},{"name":"reasons","in":"query","description":"Filter by order reasons (e.g. ONE_OFF, RESTOCK)","required":false,"schema":{"type":"array","description":"Filter by order reasons (e.g. ONE_OFF, RESTOCK)","items":{"type":"string","description":"Filter by order reasons (e.g. ONE_OFF, RESTOCK)","enum":["ONE_OFF","RESTOCK"]}}},{"name":"createdDateFrom","in":"query","description":"Filter orders created on or after this date (ISO-8601). If provided, createdDateTo must also be provided.","required":false,"schema":{"type":"string","format":"date","description":"Filter orders created on or after this date (ISO-8601). If provided, createdDateTo must also be provided.","example":"2024-01-01"},"example":"2024-01-01"},{"name":"createdDateTo","in":"query","description":"Filter orders created on or before this date (ISO-8601). If provided, createdDateFrom must also be provided.","required":false,"schema":{"type":"string","format":"date","description":"Filter orders created on or before this date (ISO-8601). If provided, createdDateFrom must also be provided.","example":"2024-12-31"},"example":"2024-12-31"},{"name":"expectedShipDateFrom","in":"query","description":"Filter orders with expected ship date on or after this date (ISO-8601). If provided, expectedShipDateTo must also be provided.","required":false,"schema":{"type":"string","format":"date","description":"Filter orders with expected ship date on or after this date (ISO-8601). If provided, expectedShipDateTo must also be provided.","example":"2024-01-01"},"example":"2024-01-01"},{"name":"expectedShipDateTo","in":"query","description":"Filter orders with expected ship date on or before this date (ISO-8601). If provided, expectedShipDateFrom must also be provided.","required":false,"schema":{"type":"string","format":"date","description":"Filter orders with expected ship date on or before this date (ISO-8601). If provided, expectedShipDateFrom must also be provided.","example":"2024-12-31"},"example":"2024-12-31"},{"name":"searchString","in":"query","description":"Search string to filter orders","required":false,"schema":{"type":"string","description":"Search string to filter orders","example":"laptop"},"example":"laptop"},{"name":"vendorSku","in":"query","description":"Filter by SKU vendor SKUs (MPN).","required":false,"schema":{"type":"array","description":"Filter by SKU vendor SKUs (MPN).","items":{"type":"string","description":"Filter by SKU vendor SKUs (MPN)."}}},{"name":"skuId","in":"query","description":"Filter by SKU IDs.","required":false,"schema":{"type":"array","description":"Filter by SKU IDs.","items":{"type":"string","format":"uuid","description":"Filter by SKU IDs."}}},{"name":"serialNumber","in":"query","description":"Filter by inventory serial numbers.","required":false,"schema":{"type":"array","description":"Filter by inventory serial numbers.","items":{"type":"string","description":"Filter by inventory serial numbers."}}},{"name":"sortBy","in":"query","description":"Field to sort by (createdAt, updatedAt, warehouse, status, submittedBy).","required":false,"schema":{"type":"string","description":"Field to sort by (createdAt, updatedAt, warehouse, status, submittedBy).","example":"createdAt"},"example":"createdAt"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC).","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC).","example":"DESC"},"example":"DESC"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid filter or pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of inventory orders","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InventoryOrderResponse"}}}}}}},"post":{"tags":["Inventory Orders"],"summary":"Create an inventory order","description":"Creates an inventory order to ship equipment from a supplier or customer to a Firstbase warehouse. Specify the destination warehouse and the items (SKUs with quantities) to be stocked. The created order begins in SUBMITTED status and will be processed by the Firstbase logistics team.","operationId":"createInventoryOrder_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryOrderRequest"}}},"required":true},"responses":{"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request. Returns source \"ASSET_TRACKING_ONLY_GEO\" when the destination country or region is configured as asset-tracking-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Inventory order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryOrderResponse"}}}}}}},"/api/v1/inventory-levels":{"get":{"tags":["Inventory Levels"],"summary":"List inventory level configurations for the authenticated organization","description":"Returns a paginated list of inventory level configurations (min/max stock rules) for the caller's organization. Each record defines the minimum and maximum quantity thresholds for a specific SKU at a specific warehouse. Supports filtering by SKU, warehouse, region, category, brand, and active status.","operationId":"listInventoryLevels","parameters":[{"name":"page","in":"query","description":"Page number (1-based, default: 1)","required":false,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page (max: 1000, default: 100)","required":false,"schema":{"type":"integer","format":"int32","default":100},"example":100},{"name":"skuIds","in":"query","description":"Filter by one or more SKU IDs","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"warehouseIds","in":"query","description":"Filter by one or more warehouse IDs","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"regionIds","in":"query","description":"Filter by one or more region IDs","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"categories","in":"query","description":"Filter by one or more product category codes (e.g. COMPUTER, MONITOR)","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"brands","in":"query","description":"Filter by one or more vendor/brand codes","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"searchString","in":"query","description":"Search by product title (partial match)","required":false,"schema":{"type":"string"}},{"name":"active","in":"query","description":"Filter by active status — true returns active levels only, false returns inactive only (default: true)","required":false,"schema":{"type":"boolean","default":true}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of inventory level configurations with current stock details","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InventoryLevelResponse"}}}}}}},"post":{"tags":["Inventory Levels"],"summary":"Create a new inventory level configuration for a SKU at a warehouse","description":"Creates an inventory level configuration that defines the minimum and maximum stock thresholds for a specific SKU at a specific warehouse. Optionally scoped to a region. Returns 409 if a level already exists for the same SKU + warehouse + region combination.","operationId":"createInventoryLevel","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryLevelRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — validation error or invalid SKU/warehouse/region","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"An inventory level already exists for this SKU, warehouse, and region combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Inventory level created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLevelResponse"}}}}}}},"/api/inventory-levels":{"get":{"tags":["Inventory Levels"],"summary":"List inventory level configurations for the authenticated organization","description":"Returns a paginated list of inventory level configurations (min/max stock rules) for the caller's organization. Each record defines the minimum and maximum quantity thresholds for a specific SKU at a specific warehouse. Supports filtering by SKU, warehouse, region, category, brand, and active status.","operationId":"listInventoryLevels_1","parameters":[{"name":"page","in":"query","description":"Page number (1-based, default: 1)","required":false,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page (max: 1000, default: 100)","required":false,"schema":{"type":"integer","format":"int32","default":100},"example":100},{"name":"skuIds","in":"query","description":"Filter by one or more SKU IDs","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"warehouseIds","in":"query","description":"Filter by one or more warehouse IDs","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"regionIds","in":"query","description":"Filter by one or more region IDs","required":false,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"categories","in":"query","description":"Filter by one or more product category codes (e.g. COMPUTER, MONITOR)","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"brands","in":"query","description":"Filter by one or more vendor/brand codes","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"searchString","in":"query","description":"Search by product title (partial match)","required":false,"schema":{"type":"string"}},{"name":"active","in":"query","description":"Filter by active status — true returns active levels only, false returns inactive only (default: true)","required":false,"schema":{"type":"boolean","default":true}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of inventory level configurations with current stock details","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InventoryLevelResponse"}}}}}}},"post":{"tags":["Inventory Levels"],"summary":"Create a new inventory level configuration for a SKU at a warehouse","description":"Creates an inventory level configuration that defines the minimum and maximum stock thresholds for a specific SKU at a specific warehouse. Optionally scoped to a region. Returns 409 if a level already exists for the same SKU + warehouse + region combination.","operationId":"createInventoryLevel_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryLevelRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — validation error or invalid SKU/warehouse/region","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"An inventory level already exists for this SKU, warehouse, and region combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Inventory level created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLevelResponse"}}}}}}},"/api/assets":{"post":{"tags":["Assets"],"summary":"Create an asset","description":"Creates a new asset (inventory item) in the organization's inventory. Identify the product either by sku_id (for known SKUs) or by category_code + description (for custom products). Assign the asset to a person (person_id) or an office (office_id).","operationId":"createAsset","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssetRequest"}}},"required":true},"responses":{"404":{"description":"Person, office, or SKU not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Asset created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetResponse"}}}},"403":{"description":"Forbidden — feature flag is disabled or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/assets":{"post":{"tags":["Assets"],"summary":"Create an asset","description":"Creates a new asset (inventory item) in the organization's inventory. Identify the product either by sku_id (for known SKUs) or by category_code + description (for custom products). Assign the asset to a person (person_id) or an office (office_id).","operationId":"createAsset_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssetRequest"}}},"required":true},"responses":{"404":{"description":"Person, office, or SKU not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Asset created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetResponse"}}}},"403":{"description":"Forbidden — feature flag is disabled or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/shipment-notices":{"get":{"tags":["Shipment Notices"],"summary":"List shipment notice orders — DEPRECATED, use /api/v1/shipment-notices","description":"DEPRECATED: returns only one serial number per package item. Use /api/v1/shipment-notices to receive the full inventories list per item. Returns a paginated list of shipment notice orders for the caller's organization.","operationId":"listShipmentNotices","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":100},"example":100},{"name":"status","in":"query","description":"Filter by shipment notice order statuses","required":false,"schema":{"type":"array","description":"Filter by shipment notice order statuses","items":{"type":"string","description":"Filter by shipment notice order statuses","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","NOT_COMPLETED","CANCELLED"]}}},{"name":"condition","in":"query","description":"Filter by shipment notice order conditions","required":false,"schema":{"type":"array","description":"Filter by shipment notice order conditions","items":{"type":"string","description":"Filter by shipment notice order conditions","enum":["NEW","USED"]}}},{"name":"source","in":"query","description":"Filter by source types","required":false,"schema":{"type":"array","description":"Filter by source types","items":{"type":"string","description":"Filter by source types","enum":["SUPPLIER","OFFICE"]}}},{"name":"shipToWarehouse","in":"query","description":"Filter by destination warehouse IDs","required":false,"schema":{"type":"array","description":"Filter by destination warehouse IDs","items":{"type":"string","format":"uuid","description":"Filter by destination warehouse IDs"}}},{"name":"brand","in":"query","description":"Filter by vendor / brand codes","required":false,"schema":{"type":"array","description":"Filter by vendor / brand codes","example":"APPLE","items":{"type":"string","description":"Filter by vendor / brand codes","example":"APPLE"}},"example":"APPLE"},{"name":"category","in":"query","description":"Filter by category codes","required":false,"schema":{"type":"array","description":"Filter by category codes","example":"COMPUTER","items":{"type":"string","description":"Filter by category codes","example":"COMPUTER"}},"example":"COMPUTER"},{"name":"poNumber","in":"query","description":"Filter by purchase order numbers","required":false,"schema":{"type":"array","description":"Filter by purchase order numbers","items":{"type":"string","description":"Filter by purchase order numbers"}}},{"name":"vendorSku","in":"query","description":"Filter by vendor SKUs","required":false,"schema":{"type":"array","description":"Filter by vendor SKUs","items":{"type":"string","description":"Filter by vendor SKUs"}}},{"name":"skuId","in":"query","description":"Filter by SKU IDs","required":false,"schema":{"type":"array","description":"Filter by SKU IDs","items":{"type":"string","format":"uuid","description":"Filter by SKU IDs"}}},{"name":"serialNumber","in":"query","description":"Filter by serial numbers of received inventory items","required":false,"schema":{"type":"array","description":"Filter by serial numbers of received inventory items","items":{"type":"string","description":"Filter by serial numbers of received inventory items"}}},{"name":"orderDateFrom","in":"query","description":"Order date range start (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Order date range start (ISO-8601)","example":"2024-01-01"},"example":"2024-01-01"},{"name":"orderDateTo","in":"query","description":"Order date range end (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Order date range end (ISO-8601)","example":"2024-12-31"},"example":"2024-12-31"},{"name":"sortBy","in":"query","description":"Sort field (createdAt, updatedAt, warehouse, status, submittedBy)","required":false,"schema":{"type":"string","description":"Sort field (createdAt, updatedAt, warehouse, status, submittedBy)","example":"createdAt"},"example":"createdAt"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"DESC"},"example":"DESC"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid filter or pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of shipment notice orders (legacy format)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentNoticeOrderResponse"}}}}},"403":{"description":"Feature not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}},"deprecated":true},"post":{"tags":["Shipment Notices"],"summary":"Create a shipment notice","description":"Creates a new shipment notice order. Identify the source as SUPPLIER (with purchase_order_number) or OFFICE. Each shipment contains items identified by sku_id with a quantity.","operationId":"createShipmentNoticeLegacy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShipmentNoticeRequest"}}},"required":true},"responses":{"404":{"description":"Warehouse, office, or SKU not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — validation error or invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"201":{"description":"Shipment notice created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNoticeResponse"}}}},"403":{"description":"Forbidden — feature flag is disabled or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}},"deprecated":true}},"/api/identity/hook/token":{"post":{"tags":["okta-token-hook-controller"],"operationId":"handleTokenHook","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OktaTokenHookRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/OktaTokenHookResponse"}}}}}}},"/api/identity/hook/service-account-token":{"post":{"tags":["okta-token-hook-controller"],"operationId":"handleServiceAccountTokenHook","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OktaTokenHookRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/OktaTokenHookResponse"}}}}}}},"/api/v1/shipment-notices/{shipmentNoticeId}":{"delete":{"tags":["Shipment Notices V1"],"summary":"Cancel shipment notice","description":"Cancels a shipment notice. Allowed only when notice status is SUBMITTED. Cascades all package item statuses to CANCELLED.","operationId":"deleteShipmentNotice","parameters":[{"name":"shipmentNoticeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Shipment notice not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Shipment notice status does not allow cancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Shipment notice cancelled"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}},"patch":{"tags":["Shipment Notices V1"],"summary":"Modify shipment notice","description":"Partially updates a shipment notice and its packages/items. Editability follows the rule: shipment notice editable when SUBMITTED or PROCESSING with at least one PENDING package. Use `{id, delete: true}` on shipmentNoticePackages or items to remove them. Omit elements to preserve them. Add new packages or items by omitting `id`.","operationId":"patchShipmentNotice","parameters":[{"name":"shipmentNoticeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchShipmentNoticeRequest"}}},"required":true},"responses":{"404":{"description":"Shipment notice not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Shipment notice updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNoticeOrderResponseV1"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/shipment-notices/{shipmentNoticeId}":{"delete":{"tags":["Shipment Notices V1"],"summary":"Cancel shipment notice","description":"Cancels a shipment notice. Allowed only when notice status is SUBMITTED. Cascades all package item statuses to CANCELLED.","operationId":"deleteShipmentNotice_1","parameters":[{"name":"shipmentNoticeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Shipment notice not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Shipment notice status does not allow cancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Shipment notice cancelled"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}},"patch":{"tags":["Shipment Notices V1"],"summary":"Modify shipment notice","description":"Partially updates a shipment notice and its packages/items. Editability follows the rule: shipment notice editable when SUBMITTED or PROCESSING with at least one PENDING package. Use `{id, delete: true}` on shipmentNoticePackages or items to remove them. Omit elements to preserve them. Add new packages or items by omitting `id`.","operationId":"patchShipmentNotice_1","parameters":[{"name":"shipmentNoticeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchShipmentNoticeRequest"}}},"required":true},"responses":{"404":{"description":"Shipment notice not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Shipment notice updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNoticeOrderResponseV1"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/return-orders/{returnOrderId}/items":{"patch":{"tags":["Return Orders"],"summary":"Process return items","description":"Bulk-update items on a return order (used when items physically arrive). Each item: `id`, `status`. When `status` is NOT_RETURNED, send `notReturnedDisposition` DEPLOYED (keep deployed; omit deploy fields) or ARCHIVE (`deployReason` required; non-blank `deployReasonDetails` when deployReason is OTHER). Matches org-app Process Return. Offboarding returns: domain validation may still require deployReason for NOT_RETURNED. Additional RETURNED validation may return 400 with domain detail.","operationId":"patchReturnOrderItems","parameters":[{"name":"returnOrderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchReturnOrderItemsRequest"}}},"required":true},"responses":{"404":{"description":"Return order or item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Items updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchReturnOrderItemsResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/return-orders/{returnOrderId}/items":{"patch":{"tags":["Return Orders"],"summary":"Process return items","description":"Bulk-update items on a return order (used when items physically arrive). Each item: `id`, `status`. When `status` is NOT_RETURNED, send `notReturnedDisposition` DEPLOYED (keep deployed; omit deploy fields) or ARCHIVE (`deployReason` required; non-blank `deployReasonDetails` when deployReason is OTHER). Matches org-app Process Return. Offboarding returns: domain validation may still require deployReason for NOT_RETURNED. Additional RETURNED validation may return 400 with domain detail.","operationId":"patchReturnOrderItems_1","parameters":[{"name":"returnOrderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchReturnOrderItemsRequest"}}},"required":true},"responses":{"404":{"description":"Return order or item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Items updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchReturnOrderItemsResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/packages/{slug}/notes/{noteId}":{"patch":{"tags":["Packages"],"summary":"Modify an existing package note","description":"Partially update a single note attached to a package. Modifiable fields: `note`, `active`. Setting `active=false` soft-deletes the note. The response includes the full package view plus its `notes` collection (upsert semantics surfaced via the refreshed `notes` array).","operationId":"patchPackageNote","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"noteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchPackageNoteRequest"}}},"required":true},"responses":{"404":{"description":"Package or note not found for the authenticated organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Empty body, invalid field values, or explicit null for guarded scalar fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Package note cannot be modified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"403":{"description":"Endpoint not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Package note updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPackageResponse"}}}}}}},"/api/packages/{slug}/notes/{noteId}":{"patch":{"tags":["Packages"],"summary":"Modify an existing package note","description":"Partially update a single note attached to a package. Modifiable fields: `note`, `active`. Setting `active=false` soft-deletes the note. The response includes the full package view plus its `notes` collection (upsert semantics surfaced via the refreshed `notes` array).","operationId":"patchPackageNote_1","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"noteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchPackageNoteRequest"}}},"required":true},"responses":{"404":{"description":"Package or note not found for the authenticated organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Empty body, invalid field values, or explicit null for guarded scalar fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Package note cannot be modified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"403":{"description":"Endpoint not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Package note updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPackageResponse"}}}}}}},"/api/v1/packages/{slug}":{"get":{"tags":["Packages"],"summary":"Get a single package by its unique slug","description":"Returns full details for a single equipment package identified by its URL-safe slug. Includes the package's SKUs, rules, notes, and configuration fields.","operationId":"getPackageBySlug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"404":{"description":"Package not found for the authenticated organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"403":{"description":"Endpoint not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested package","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPackageResponse"}}}}}},"patch":{"tags":["Packages"],"summary":"Modify an existing package","description":"Partially update a package by slug. Modifiable scalar fields: `name`, `active`, `approvalRequired`, `automaticOrder`, `defaultOfficeId`, `deliverySetting`. When `skus` is present, each entry adds or removes a SKU by catalog `id` (set `delete: true` to unlink). Omitted existing SKUs are unchanged; omit `skus` to leave assignments unchanged. `rules` and `usedEquipmentPreferences` replace when present (REQ-025). Setting `active=false` soft-deletes the package. The response includes the full package view plus its `notes` collection. Business-rule rejections (illegal automatic order, duplicate name, archive blocked, etc.) return HTTP 409 with `source=\"package\"` envelope.","operationId":"patchPackage","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchPackageRequest"}}},"required":true},"responses":{"404":{"description":"Package not found for the authenticated organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Empty body, invalid field values, or explicit null for guarded scalar fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Package cannot be modified (illegal automatic order, duplicate name, archive blocked, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"403":{"description":"Endpoint not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Package updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPackageResponse"}}}}}}},"/api/packages/{slug}":{"get":{"tags":["Packages"],"summary":"Get a single package by its unique slug","description":"Returns full details for a single equipment package identified by its URL-safe slug. Includes the package's SKUs, rules, notes, and configuration fields.","operationId":"getPackageBySlug_1","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"404":{"description":"Package not found for the authenticated organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"403":{"description":"Endpoint not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested package","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPackageResponse"}}}}}},"patch":{"tags":["Packages"],"summary":"Modify an existing package","description":"Partially update a package by slug. Modifiable scalar fields: `name`, `active`, `approvalRequired`, `automaticOrder`, `defaultOfficeId`, `deliverySetting`. When `skus` is present, each entry adds or removes a SKU by catalog `id` (set `delete: true` to unlink). Omitted existing SKUs are unchanged; omit `skus` to leave assignments unchanged. `rules` and `usedEquipmentPreferences` replace when present (REQ-025). Setting `active=false` soft-deletes the package. The response includes the full package view plus its `notes` collection. Business-rule rejections (illegal automatic order, duplicate name, archive blocked, etc.) return HTTP 409 with `source=\"package\"` envelope.","operationId":"patchPackage_1","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchPackageRequest"}}},"required":true},"responses":{"404":{"description":"Package not found for the authenticated organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Empty body, invalid field values, or explicit null for guarded scalar fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Package cannot be modified (illegal automatic order, duplicate name, archive blocked, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"403":{"description":"Endpoint not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Package updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPackageResponse"}}}}}}},"/api/v1/orders/{orderId}":{"get":{"tags":["Orders"],"summary":"Get a single order by ID","description":"Returns full details for a single order belonging to the caller's organization, including order items, current status, and shipping address.","operationId":"getOrderById","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Order not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}},"patch":{"tags":["Orders"],"summary":"Modify or cancel an existing order","description":"Partially update an existing order. Allowed before fulfilment. All request body fields are optional — omit any field to leave it unchanged.\n\n**Cancel an order:** send only `{\"status\": \"CANCELLED\"}`. Works for orders in ORDERED, AWAITING_APPROVAL, or DECLINED status (not SHIPPED). This is the correct way to cancel an equipment order; there is no DELETE endpoint for `/api/v1/orders`.\n\nOther modifiable fields: products, shippingAddress, deliverToPersonId, deliverToOfficeId. Address validation workflow is unchanged by this endpoint (same as logistics modify-order: `addressValidationNeeded` is not set via PATCH). Each `products[]` line uses the same `preferredCondition` rules as create order (`skus[]`): NEW, USED, or omitted (defaults to NEW-only preference server-side). When `products` is sent, omitted existing line ids are left unchanged; cancel a line with `cancelled: true` and its `id`. New lines omit `id`. The response `orderItems` list includes cancelled rows—filter by `status` for active lines only.","operationId":"patchOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchOrderRequest"}}},"required":true},"responses":{"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Order is not editable or violates package rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Order updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}},"403":{"description":"Endpoint not available for this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/orders/{orderId}":{"get":{"tags":["Orders"],"summary":"Get a single order by ID","description":"Returns full details for a single order belonging to the caller's organization, including order items, current status, and shipping address.","operationId":"getOrderById_1","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Order not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}}}},"patch":{"tags":["Orders"],"summary":"Modify or cancel an existing order","description":"Partially update an existing order. Allowed before fulfilment. All request body fields are optional — omit any field to leave it unchanged.\n\n**Cancel an order:** send only `{\"status\": \"CANCELLED\"}`. Works for orders in ORDERED, AWAITING_APPROVAL, or DECLINED status (not SHIPPED). This is the correct way to cancel an equipment order; there is no DELETE endpoint for `/api/v1/orders`.\n\nOther modifiable fields: products, shippingAddress, deliverToPersonId, deliverToOfficeId. Address validation workflow is unchanged by this endpoint (same as logistics modify-order: `addressValidationNeeded` is not set via PATCH). Each `products[]` line uses the same `preferredCondition` rules as create order (`skus[]`): NEW, USED, or omitted (defaults to NEW-only preference server-side). When `products` is sent, omitted existing line ids are left unchanged; cancel a line with `cancelled: true` and its `id`. New lines omit `id`. The response `orderItems` list includes cancelled rows—filter by `status` for active lines only.","operationId":"patchOrder_1","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchOrderRequest"}}},"required":true},"responses":{"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Order is not editable or violates package rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Order updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse"}}}},"403":{"description":"Endpoint not available for this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/offices/{officeId}":{"patch":{"tags":["Offices"],"summary":"Modify an existing office","description":"Partially update an office. Modifiable fields: `name`, `contactName`, `address` (full-object replace when present), `active`. Setting `active=false` soft-deletes the office. Reactivation (`active=true`) is not supported and returns 400. Business-rule rejections (active inventory, active return orders, default-office-for-package) return HTTP 409 with `source=\"office\"` envelope.","operationId":"patchOffice","parameters":[{"name":"officeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchOfficeRequest"}}},"required":true},"responses":{"404":{"description":"Office not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Empty body, invalid field values, explicit null for `name`, `address`, or `active`, or attempted reactivation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Office cannot be modified (editability rule, duplicate name, country change, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Office updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficeResponse"}}}},"403":{"description":"Endpoint not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/offices/{officeId}":{"patch":{"tags":["Offices"],"summary":"Modify an existing office","description":"Partially update an office. Modifiable fields: `name`, `contactName`, `address` (full-object replace when present), `active`. Setting `active=false` soft-deletes the office. Reactivation (`active=true`) is not supported and returns 400. Business-rule rejections (active inventory, active return orders, default-office-for-package) return HTTP 409 with `source=\"office\"` envelope.","operationId":"patchOffice_1","parameters":[{"name":"officeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchOfficeRequest"}}},"required":true},"responses":{"404":{"description":"Office not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Empty body, invalid field values, explicit null for `name`, `address`, or `active`, or attempted reactivation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Office cannot be modified (editability rule, duplicate name, country change, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Office updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficeResponse"}}}},"403":{"description":"Endpoint not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/inventory/{inventoryId}":{"get":{"tags":["Inventory"],"summary":"Get a single inventory item by ID","description":"Returns full details for a single inventory item belonging to the caller's organization. Returns 400 if the inventory does not belong to the organization.","operationId":"getInventory","parameters":[{"name":"inventoryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — inventory not found or does not belong to the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested inventory item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inventory"}}}}}},"patch":{"tags":["Inventory"],"summary":"Update inventory details","operationId":"updateInventory","parameters":[{"name":"inventoryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Inventory updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inventory"}}}}}}},"/api/inventory/{inventoryId}":{"get":{"tags":["Inventory"],"summary":"Get a single inventory item by ID","description":"Returns full details for a single inventory item belonging to the caller's organization. Returns 400 if the inventory does not belong to the organization.","operationId":"getInventory_1","parameters":[{"name":"inventoryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — inventory not found or does not belong to the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested inventory item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inventory"}}}}}},"patch":{"tags":["Inventory"],"summary":"Update inventory details","operationId":"updateInventory_1","parameters":[{"name":"inventoryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryRequest"}}},"required":true},"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Inventory updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inventory"}}}}}}},"/api/inventory-orders/{inventoryOrderId}":{"delete":{"tags":["Inventory Orders"],"summary":"Cancel an inventory order","description":"Cancels an inventory order. Allowed only when the order is in SUBMITTED status.","operationId":"cancelInventoryOrder","parameters":[{"name":"inventoryOrderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Inventory order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Order is not in SUBMITTED status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Inventory order cancelled"},"403":{"description":"Endpoint not available for this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}},"patch":{"tags":["Inventory Orders"],"summary":"Modify an inventory order","description":"Partially update an inventory order. Field writability depends on order status — see request body schema.","operationId":"patchInventoryOrder","parameters":[{"name":"inventoryOrderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchInventoryOrderRequest"}}},"required":true},"responses":{"404":{"description":"Inventory order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request (empty body, validation error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Order status forbids this modification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Inventory order updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryOrderResponse"}}}},"403":{"description":"Endpoint not available for this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/inventory-orders/{inventoryOrderId}":{"delete":{"tags":["Inventory Orders"],"summary":"Cancel an inventory order","description":"Cancels an inventory order. Allowed only when the order is in SUBMITTED status.","operationId":"cancelInventoryOrder_1","parameters":[{"name":"inventoryOrderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Inventory order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Order is not in SUBMITTED status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Inventory order cancelled"},"403":{"description":"Endpoint not available for this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}},"patch":{"tags":["Inventory Orders"],"summary":"Modify an inventory order","description":"Partially update an inventory order. Field writability depends on order status — see request body schema.","operationId":"patchInventoryOrder_1","parameters":[{"name":"inventoryOrderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIPatchInventoryOrderRequest"}}},"required":true},"responses":{"404":{"description":"Inventory order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request (empty body, validation error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Order status forbids this modification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Inventory order updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryOrderResponse"}}}},"403":{"description":"Endpoint not available for this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/inventory-levels/{id}":{"delete":{"tags":["Inventory Levels"],"summary":"Delete (deactivate) an inventory level by ID","description":"Soft-deletes (deactivates) an inventory level configuration. The record is not permanently removed; reactivation requires creating a new configuration via POST.","operationId":"deleteInventoryLevel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Inventory level not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Inventory level deactivated successfully"}}},"patch":{"tags":["Inventory Levels"],"summary":"Update an inventory level","description":"\n        Partial update for inventory level thresholds and reordering settings.\n\n        Fields accepted: minQuantity, maxQuantity, includeUsed, autoCreate, active, customerPoNumber.\n\n        skuId, warehouseId, and regionId are NOT accepted (immutable after creation) — sending\n        any of them returns 400 with a per-field error message. Any other field name returns\n        400 'Unknown field: <name>'. Sending an empty body returns 400 'At least one modifiable\n        field must be provided'.\n\n        Setting active=false soft-deletes the level. Reactivating via PATCH (active=true on an\n        inactive level) is not supported; use POST /api/inventory-levels. Sending active=true\n        on an already-active level is a 200 no-op (no state change, no write).\n    ","operationId":"updateInventoryLevel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryLevelRequest"}}},"required":true},"responses":{"404":{"description":"Inventory level not found (or not visible to the caller's organization)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — validation, immutable field, unknown field, empty body, or reactivation attempt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Inventory level updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLevelResponse"}}}}}}},"/api/inventory-levels/{id}":{"delete":{"tags":["Inventory Levels"],"summary":"Delete (deactivate) an inventory level by ID","description":"Soft-deletes (deactivates) an inventory level configuration. The record is not permanently removed; reactivation requires creating a new configuration via POST.","operationId":"deleteInventoryLevel_1","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Inventory level not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Inventory level deactivated successfully"}}},"patch":{"tags":["Inventory Levels"],"summary":"Update an inventory level","description":"\n        Partial update for inventory level thresholds and reordering settings.\n\n        Fields accepted: minQuantity, maxQuantity, includeUsed, autoCreate, active, customerPoNumber.\n\n        skuId, warehouseId, and regionId are NOT accepted (immutable after creation) — sending\n        any of them returns 400 with a per-field error message. Any other field name returns\n        400 'Unknown field: <name>'. Sending an empty body returns 400 'At least one modifiable\n        field must be provided'.\n\n        Setting active=false soft-deletes the level. Reactivating via PATCH (active=true on an\n        inactive level) is not supported; use POST /api/inventory-levels. Sending active=true\n        on an already-active level is a 200 no-op (no state change, no write).\n    ","operationId":"updateInventoryLevel_1","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryLevelRequest"}}},"required":true},"responses":{"404":{"description":"Inventory level not found (or not visible to the caller's organization)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — validation, immutable field, unknown field, empty body, or reactivation attempt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Inventory level updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryLevelResponse"}}}}}}},"/api/v1/warehouses":{"get":{"tags":["Warehouses V1"],"summary":"List warehouses accessible to the authenticated organization (V1)","description":"Returns a paginated list of Firstbase warehouses that the caller's organization can use when creating inventory orders or shipment notices. Optionally filter by country code (ISO 3166-1 alpha-2). Page and size are 1-based and capped at 100 per page.","operationId":"listWarehousesV1","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":100,"maximum":100,"minimum":1}},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Invalid pagination parameters — page or size out of range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of warehouses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDTO"}}}},"403":{"description":"Endpoint not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/warehouses/{id}":{"get":{"tags":["Warehouses V1"],"summary":"Get a single warehouse by ID (V1)","description":"Returns full details for a single warehouse accessible to the caller's organization.","operationId":"getWarehouseV1","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Warehouse not found or not accessible to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested warehouse","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseResponseDto"}}}},"403":{"description":"Endpoint not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/shipments":{"get":{"tags":["Shipment"],"summary":"Look up shipment details by tracking numbers","description":"Returns shipment details for the provided tracking numbers, paginated. At least one tracking number must be supplied. Each result includes carrier, tracking status, and the order items associated with the shipment.","operationId":"listShipments","parameters":[{"name":"trackingNumbers","in":"query","description":"One or more carrier tracking numbers to look up (required)","required":true,"schema":{"type":"array","items":{"type":"string"}},"example":"1Z999AA10123456784"},{"name":"page","in":"query","description":"Page number to return (1-based, default: 1)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page (default: 10)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":10},"example":10}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — missing or invalid trackingNumbers parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of shipment details matching the provided tracking numbers","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaginatedShipmentDetailsDto"}}}}}}}},"/api/v1/shipments":{"get":{"tags":["Shipment"],"summary":"Look up shipment details by tracking numbers","description":"Returns shipment details for the provided tracking numbers, paginated. At least one tracking number must be supplied. Each result includes carrier, tracking status, and the order items associated with the shipment.","operationId":"listShipments_1","parameters":[{"name":"trackingNumbers","in":"query","description":"One or more carrier tracking numbers to look up (required)","required":true,"schema":{"type":"array","items":{"type":"string"}},"example":"1Z999AA10123456784"},{"name":"page","in":"query","description":"Page number to return (1-based, default: 1)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page (default: 10)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":10},"example":10}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — missing or invalid trackingNumbers parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of shipment details matching the provided tracking numbers","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaginatedShipmentDetailsDto"}}}}}}}},"/api/v1/shipment-notices/{id}":{"get":{"tags":["Shipment Notices V1"],"summary":"Get a single shipment notice order by ID (V1)","description":"Returns full details for a single shipment notice order belonging to the caller's organization. Each package item includes a full `inventories` list with individual serial numbers and inventory IDs.","operationId":"getShipmentNoticeV1","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Shipment notice order not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested shipment notice order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNoticeOrderResponseV1"}}}},"403":{"description":"Feature not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/returns/{id}":{"get":{"tags":["Returns"],"summary":"Get a single return order by ID","description":"Returns full details for a single return order belonging to the caller's organization. Optionally includes shipment tracking information when includeShipment=true.","operationId":"getReturn","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"includeShipment","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"404":{"description":"Return order not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested return order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnOrderInfo"}}}}}}},"/api/returns/{id}":{"get":{"tags":["Returns"],"summary":"Get a single return order by ID","description":"Returns full details for a single return order belonging to the caller's organization. Optionally includes shipment tracking information when includeShipment=true.","operationId":"getReturn_1","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"includeShipment","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"404":{"description":"Return order not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested return order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnOrderInfo"}}}}}}},"/api/replacements/{id}":{"get":{"tags":["Replacements"],"summary":"Get a replacement by ID","description":"Returns the details of a single replacement order by its unique identifier.","operationId":"getReplacementById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Replacement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The replacement order matching the given ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetReplacementResponse"}}}}}}},"/api/v1/replacements/{id}":{"get":{"tags":["Replacements"],"summary":"Get a replacement by ID","description":"Returns the details of a single replacement order by its unique identifier.","operationId":"getReplacementById_1","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Replacement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The replacement order matching the given ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPIGetReplacementResponse"}}}}}}},"/api/v1/regions":{"get":{"tags":["Regions V1"],"summary":"List regions accessible to the authenticated organization (V1)","description":"Returns a paginated list of geographic regions associated with the caller's organization. Regions define where inventory levels apply and where warehouses operate. Optionally filter by region name (partial match) or region code. Page and size are 1-based and capped at 100 per page.","operationId":"listRegionsV1","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":100,"maximum":100,"minimum":1}},{"name":"name","in":"query","required":false,"schema":{"type":"string"}},{"name":"regionCode","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Invalid pagination parameters — page or size out of range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of regions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDTO"}}}},"403":{"description":"Endpoint not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/regions/{id}":{"get":{"tags":["Regions V1"],"summary":"Get a single region by ID (V1)","description":"Returns full details for a single region accessible to the caller's organization.","operationId":"getRegionV1","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Region not found or not accessible to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested region","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionResponseDto"}}}},"403":{"description":"Endpoint not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/offices/{id}":{"get":{"tags":["Offices"],"summary":"Get a single office by ID","description":"Returns full details for a single office belonging to the caller's organization.","operationId":"getOffice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Office not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested office","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficeResponse"}}}},"403":{"description":"Endpoint not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/offices/{id}":{"get":{"tags":["Offices"],"summary":"Get a single office by ID","description":"Returns full details for a single office belonging to the caller's organization.","operationId":"getOffice_1","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Office not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested office","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficeResponse"}}}},"403":{"description":"Endpoint not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/offices":{"get":{"tags":["Offices"],"summary":"List all offices for the authenticated organization","description":"Returns a paginated list of offices belonging to the caller's organization. Supports pagination. Active and inactive offices are both returned unless filtered.","operationId":"listOffices","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":100},"example":100}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of offices","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OfficeResponse"}}}}},"403":{"description":"Endpoint not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/offices":{"get":{"tags":["Offices"],"summary":"List all offices for the authenticated organization","description":"Returns a paginated list of offices belonging to the caller's organization. Supports pagination. Active and inactive offices are both returned unless filtered.","operationId":"listOffices_1","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":100},"example":100}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of offices","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OfficeResponse"}}}}},"403":{"description":"Endpoint not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/new-joiners/stats":{"get":{"tags":["New Joiners"],"summary":"Get new joiner stats","description":"Aggregate counts for status cards and provisioning outcomes. Accepts the same filter query parameters as the list endpoint (e.g. countryCodes, equipmentReadiness, urgency) so stats reflect the filtered cohort. When startDateFrom is omitted, the domain applies a default 60-day lookback floor — supply it explicitly to widen the window beyond 60 days. Pagination and sort query parameters accepted on the list endpoint are ignored on this endpoint. Example: ?countryCodes=US&equipmentReadiness=NOT_STARTED","operationId":"getNewJoinerStats","parameters":[{"name":"searchString","in":"query","description":"Free-text search across name and email","required":false,"schema":{"type":"string","description":"Free-text search across name and email"}},{"name":"equipmentReadiness","in":"query","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","required":false,"schema":{"type":"array","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","items":{"type":"string","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","enum":["NOT_STARTED","ORDER_PLACED","READY"]}}},{"name":"urgency","in":"query","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","required":false,"schema":{"type":"array","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","items":{"type":"string","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","enum":["ON_TRACK","AT_RISK","LATE"]}}},{"name":"countryCodes","in":"query","description":"Filter by ISO country codes","required":false,"schema":{"type":"array","description":"Filter by ISO country codes","items":{"type":"string","description":"Filter by ISO country codes"}}},{"name":"provisioningOutcome","in":"query","description":"Filter by provisioning outcome: ON_TIME, LATE","required":false,"schema":{"type":"array","description":"Filter by provisioning outcome: ON_TIME, LATE","items":{"type":"string","description":"Filter by provisioning outcome: ON_TIME, LATE","enum":["ON_TIME","LATE"]}}},{"name":"startDateFrom","in":"query","description":"Start date lower bound (ISO-8601). When omitted, a default 60-day lookback floor is applied. Supply explicitly to widen the window.","required":false,"schema":{"type":"string","format":"date","description":"Start date lower bound (ISO-8601). When omitted, a default 60-day lookback floor is applied. Supply explicitly to widen the window.","example":"2026-01-01"},"example":"2026-01-01"},{"name":"startDateTo","in":"query","description":"Start date upper bound (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Start date upper bound (ISO-8601)","example":"2026-12-31"},"example":"2026-12-31"},{"name":"userStatus","in":"query","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","required":false,"schema":{"type":"array","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","items":{"type":"string","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","enum":["INVITED","ACTIVE","INACTIVE","DELETED","OFFBOARDING","CANNOT_REACTIVATE"]}}},{"name":"procurementMethod","in":"query","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","required":false,"schema":{"type":"array","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","items":{"type":"string","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","enum":["DROPSHIP","MIXED","WAREHOUSE"]}}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request (invalid parameter)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Stats retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPINewJoinerStatsResponse"}}}}}}},"/api/new-joiners/stats":{"get":{"tags":["New Joiners"],"summary":"Get new joiner stats","description":"Aggregate counts for status cards and provisioning outcomes. Accepts the same filter query parameters as the list endpoint (e.g. countryCodes, equipmentReadiness, urgency) so stats reflect the filtered cohort. When startDateFrom is omitted, the domain applies a default 60-day lookback floor — supply it explicitly to widen the window beyond 60 days. Pagination and sort query parameters accepted on the list endpoint are ignored on this endpoint. Example: ?countryCodes=US&equipmentReadiness=NOT_STARTED","operationId":"getNewJoinerStats_1","parameters":[{"name":"searchString","in":"query","description":"Free-text search across name and email","required":false,"schema":{"type":"string","description":"Free-text search across name and email"}},{"name":"equipmentReadiness","in":"query","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","required":false,"schema":{"type":"array","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","items":{"type":"string","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","enum":["NOT_STARTED","ORDER_PLACED","READY"]}}},{"name":"urgency","in":"query","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","required":false,"schema":{"type":"array","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","items":{"type":"string","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","enum":["ON_TRACK","AT_RISK","LATE"]}}},{"name":"countryCodes","in":"query","description":"Filter by ISO country codes","required":false,"schema":{"type":"array","description":"Filter by ISO country codes","items":{"type":"string","description":"Filter by ISO country codes"}}},{"name":"provisioningOutcome","in":"query","description":"Filter by provisioning outcome: ON_TIME, LATE","required":false,"schema":{"type":"array","description":"Filter by provisioning outcome: ON_TIME, LATE","items":{"type":"string","description":"Filter by provisioning outcome: ON_TIME, LATE","enum":["ON_TIME","LATE"]}}},{"name":"startDateFrom","in":"query","description":"Start date lower bound (ISO-8601). When omitted, a default 60-day lookback floor is applied. Supply explicitly to widen the window.","required":false,"schema":{"type":"string","format":"date","description":"Start date lower bound (ISO-8601). When omitted, a default 60-day lookback floor is applied. Supply explicitly to widen the window.","example":"2026-01-01"},"example":"2026-01-01"},{"name":"startDateTo","in":"query","description":"Start date upper bound (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Start date upper bound (ISO-8601)","example":"2026-12-31"},"example":"2026-12-31"},{"name":"userStatus","in":"query","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","required":false,"schema":{"type":"array","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","items":{"type":"string","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","enum":["INVITED","ACTIVE","INACTIVE","DELETED","OFFBOARDING","CANNOT_REACTIVATE"]}}},{"name":"procurementMethod","in":"query","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","required":false,"schema":{"type":"array","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","items":{"type":"string","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","enum":["DROPSHIP","MIXED","WAREHOUSE"]}}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request (invalid parameter)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Stats retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAPINewJoinerStatsResponse"}}}}}}},"/api/new-joiners":{"get":{"tags":["New Joiners"],"summary":"Get new joiners","description":"Paginated, filterable, sortable list of new joiner rows for the organization. When startDateFrom is omitted, the domain applies a default 60-day lookback floor — supply it explicitly to widen the window beyond 60 days.","operationId":"getNewJoiners","parameters":[{"name":"page","in":"query","description":"Page number (1-based)","required":false,"schema":{"type":"integer","format":"int32","default":1,"description":"Page number (1-based)","example":1,"minimum":1},"example":1},{"name":"size","in":"query","description":"Page size (1–200)","required":false,"schema":{"type":"integer","format":"int32","default":25,"description":"Page size (1–200)","example":25,"maximum":200,"minimum":1},"example":25},{"name":"sortBy","in":"query","description":"Sort field: startDate, urgency, equipmentReadiness, employee, country, personStatus, estimatedDeliveryDate, reminderCount, lastReminderSentAt, provisioningOutcome, orderDate","required":false,"schema":{"type":"string","description":"Sort field: startDate, urgency, equipmentReadiness, employee, country, personStatus, estimatedDeliveryDate, reminderCount, lastReminderSentAt, provisioningOutcome, orderDate","example":"startDate"},"example":"startDate"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"ASC"},"example":"ASC"},{"name":"searchString","in":"query","description":"Free-text search across name and email","required":false,"schema":{"type":"string","description":"Free-text search across name and email"}},{"name":"equipmentReadiness","in":"query","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","required":false,"schema":{"type":"array","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","items":{"type":"string","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","enum":["NOT_STARTED","ORDER_PLACED","READY"]}}},{"name":"urgency","in":"query","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","required":false,"schema":{"type":"array","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","items":{"type":"string","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","enum":["ON_TRACK","AT_RISK","LATE"]}}},{"name":"countryCodes","in":"query","description":"Filter by ISO country codes","required":false,"schema":{"type":"array","description":"Filter by ISO country codes","items":{"type":"string","description":"Filter by ISO country codes"}}},{"name":"provisioningOutcome","in":"query","description":"Filter by provisioning outcome: ON_TIME, LATE","required":false,"schema":{"type":"array","description":"Filter by provisioning outcome: ON_TIME, LATE","items":{"type":"string","description":"Filter by provisioning outcome: ON_TIME, LATE","enum":["ON_TIME","LATE"]}}},{"name":"startDateFrom","in":"query","description":"Start date lower bound (ISO-8601). When omitted, a default 60-day lookback floor is applied. Supply explicitly to widen the window.","required":false,"schema":{"type":"string","format":"date","description":"Start date lower bound (ISO-8601). When omitted, a default 60-day lookback floor is applied. Supply explicitly to widen the window.","example":"2026-01-01"},"example":"2026-01-01"},{"name":"startDateTo","in":"query","description":"Start date upper bound (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Start date upper bound (ISO-8601)","example":"2026-12-31"},"example":"2026-12-31"},{"name":"userStatus","in":"query","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","required":false,"schema":{"type":"array","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","items":{"type":"string","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","enum":["INVITED","ACTIVE","INACTIVE","DELETED","OFFBOARDING","CANNOT_REACTIVATE"]}}},{"name":"procurementMethod","in":"query","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","required":false,"schema":{"type":"array","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","items":{"type":"string","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","enum":["DROPSHIP","MIXED","WAREHOUSE"]}}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request (invalid parameter)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"New joiners retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicAPINewJoinerRowResponse"}}}}}}}},"/api/v1/new-joiners":{"get":{"tags":["New Joiners"],"summary":"Get new joiners","description":"Paginated, filterable, sortable list of new joiner rows for the organization. When startDateFrom is omitted, the domain applies a default 60-day lookback floor — supply it explicitly to widen the window beyond 60 days.","operationId":"getNewJoiners_1","parameters":[{"name":"page","in":"query","description":"Page number (1-based)","required":false,"schema":{"type":"integer","format":"int32","default":1,"description":"Page number (1-based)","example":1,"minimum":1},"example":1},{"name":"size","in":"query","description":"Page size (1–200)","required":false,"schema":{"type":"integer","format":"int32","default":25,"description":"Page size (1–200)","example":25,"maximum":200,"minimum":1},"example":25},{"name":"sortBy","in":"query","description":"Sort field: startDate, urgency, equipmentReadiness, employee, country, personStatus, estimatedDeliveryDate, reminderCount, lastReminderSentAt, provisioningOutcome, orderDate","required":false,"schema":{"type":"string","description":"Sort field: startDate, urgency, equipmentReadiness, employee, country, personStatus, estimatedDeliveryDate, reminderCount, lastReminderSentAt, provisioningOutcome, orderDate","example":"startDate"},"example":"startDate"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"ASC"},"example":"ASC"},{"name":"searchString","in":"query","description":"Free-text search across name and email","required":false,"schema":{"type":"string","description":"Free-text search across name and email"}},{"name":"equipmentReadiness","in":"query","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","required":false,"schema":{"type":"array","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","items":{"type":"string","description":"Filter by equipment readiness: NOT_STARTED, ORDER_PLACED, READY","enum":["NOT_STARTED","ORDER_PLACED","READY"]}}},{"name":"urgency","in":"query","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","required":false,"schema":{"type":"array","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","items":{"type":"string","description":"Filter by urgency: ON_TRACK, AT_RISK, LATE","enum":["ON_TRACK","AT_RISK","LATE"]}}},{"name":"countryCodes","in":"query","description":"Filter by ISO country codes","required":false,"schema":{"type":"array","description":"Filter by ISO country codes","items":{"type":"string","description":"Filter by ISO country codes"}}},{"name":"provisioningOutcome","in":"query","description":"Filter by provisioning outcome: ON_TIME, LATE","required":false,"schema":{"type":"array","description":"Filter by provisioning outcome: ON_TIME, LATE","items":{"type":"string","description":"Filter by provisioning outcome: ON_TIME, LATE","enum":["ON_TIME","LATE"]}}},{"name":"startDateFrom","in":"query","description":"Start date lower bound (ISO-8601). When omitted, a default 60-day lookback floor is applied. Supply explicitly to widen the window.","required":false,"schema":{"type":"string","format":"date","description":"Start date lower bound (ISO-8601). When omitted, a default 60-day lookback floor is applied. Supply explicitly to widen the window.","example":"2026-01-01"},"example":"2026-01-01"},{"name":"startDateTo","in":"query","description":"Start date upper bound (ISO-8601)","required":false,"schema":{"type":"string","format":"date","description":"Start date upper bound (ISO-8601)","example":"2026-12-31"},"example":"2026-12-31"},{"name":"userStatus","in":"query","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","required":false,"schema":{"type":"array","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","items":{"type":"string","description":"Filter by person status: INVITED, ACTIVE, INACTIVE, etc.","enum":["INVITED","ACTIVE","INACTIVE","DELETED","OFFBOARDING","CANNOT_REACTIVATE"]}}},{"name":"procurementMethod","in":"query","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","required":false,"schema":{"type":"array","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","items":{"type":"string","description":"Filter by procurement method: WAREHOUSE, DROPSHIP, MIXED","enum":["DROPSHIP","MIXED","WAREHOUSE"]}}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request (invalid parameter)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"New joiners retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicAPINewJoinerRowResponse"}}}}}}}},"/api/itad/requests/{requestId}":{"get":{"tags":["ITAD"],"summary":"Get a single ITAD request by ID","description":"Returns full details for a single IT Asset Disposition (ITAD) request belonging to the caller's organization, including all items in the request and their individual disposition statuses.","operationId":"getITADRequest","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"ITAD request not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested ITAD request with all its items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITADRequest"}}}}}}},"/api/v1/itad/requests/{requestId}":{"get":{"tags":["ITAD"],"summary":"Get a single ITAD request by ID","description":"Returns full details for a single IT Asset Disposition (ITAD) request belonging to the caller's organization, including all items in the request and their individual disposition statuses.","operationId":"getITADRequest_1","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"ITAD request not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested ITAD request with all its items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITADRequest"}}}}}}},"/api/v1/itad/eligible-assets":{"get":{"tags":["ITAD"],"summary":"List eligible ITAD assets","description":"List inventory assets eligible for ITAD disposition. Eligibility is based on category, deploy status, and other criteria.","operationId":"listEligibleITADAssets","parameters":[{"name":"page","in":"query","description":"Page number (1-based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":25,"maximum":100},"example":25},{"name":"warehouseId","in":"query","description":"Filter by warehouse ID","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"uuid"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"categoryCode","in":"query","description":"Filter by category code (e.g. COMPUTER, TABLET)","required":false,"allowEmptyValue":true,"schema":{"type":"string"},"example":"COMPUTER"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of eligible inventory assets","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Inventory"}}}}}}}},"/api/itad/eligible-assets":{"get":{"tags":["ITAD"],"summary":"List eligible ITAD assets","description":"List inventory assets eligible for ITAD disposition. Eligibility is based on category, deploy status, and other criteria.","operationId":"listEligibleITADAssets_1","parameters":[{"name":"page","in":"query","description":"Page number (1-based)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":25,"maximum":100},"example":25},{"name":"warehouseId","in":"query","description":"Filter by warehouse ID","required":false,"allowEmptyValue":true,"schema":{"type":"string","format":"uuid"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"categoryCode","in":"query","description":"Filter by category code (e.g. COMPUTER, TABLET)","required":false,"allowEmptyValue":true,"schema":{"type":"string"},"example":"COMPUTER"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of eligible inventory assets","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Inventory"}}}}}}}},"/api/v1/inventory-orders/{id}":{"get":{"tags":["Inventory Orders"],"summary":"Get an inventory order by ID","description":"Returns a single inventory order (including items and shipments) belonging to the caller's organization.","operationId":"getInventoryOrderById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Inventory order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Inventory order found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryOrderResponse"}}}}}}},"/api/inventory-orders/{id}":{"get":{"tags":["Inventory Orders"],"summary":"Get an inventory order by ID","description":"Returns a single inventory order (including items and shipments) belonging to the caller's organization.","operationId":"getInventoryOrderById_1","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Inventory order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Inventory order found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryOrderResponse"}}}}}}},"/api/v1/inventory":{"get":{"tags":["Inventory"],"summary":"List inventory items for the authenticated organization","description":"Returns a paginated list of inventory items owned by the caller's organization. Supports filtering by deploy status, person, office, category, and more. Results are sorted by creation date descending by default. Deprecated deploy statuses (GIFTED, LOCKED, OUT_FOR_REPAIR) are rejected with 400.","operationId":"listInventories","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":10,"maximum":100,"minimum":1},"example":10},{"name":"personId","in":"query","description":"Id of a person to which inventory is assigned","required":false,"schema":{"type":"string","description":"Id of a person to which inventory is assigned","example":"00000000-0000-0000-0000-000000000000"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"warehouseId","in":"query","description":"Id of a warehouse to which inventory is assigned","required":false,"schema":{"type":"string","description":"Id of a warehouse to which inventory is assigned","example":"00000000-0000-0000-0000-000000000000"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"officeId","in":"query","description":"Id of an office to which inventory is assigned","required":false,"schema":{"type":"string","description":"Id of an office to which inventory is assigned","example":"00000000-0000-0000-0000-000000000000"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"categories","in":"query","required":false,"schema":{"type":"array","description":"The code of the categories","items":{"type":"string"}}},{"name":"assignedCountryCode","in":"query","required":false,"schema":{"type":"array","description":"Assigned country/region codes such as DE or EU. Ignored when regional transfer is allowed.","items":{"type":"string"}}},{"name":"deployStatuses","in":"query","required":false,"schema":{"type":"array","description":"The deployment statuses","items":{"type":"string","enum":["ARCHIVED","AVAILABLE","AWAITING_ARRIVAL","DEPLOYED","GIFTED","LOCKED","ON_HOLD","OUT_FOR_REPAIR","UNAVAILABLE","VOIDED"],"example":"DEPLOYED"}}},{"name":"skuIds","in":"query","required":false,"schema":{"type":"array","description":"Ids of SKU","items":{"type":"string","format":"uuid"}}},{"name":"searchString","in":"query","description":"Keyword to search for - This searches the description, the name of the manufacturer, the category, the item's title, and the serial number.","required":false,"schema":{"type":"string","description":"Keyword to search for - This searches the description, the name of the manufacturer, the category, the item's title, and the serial number.","example":"Air"},"example":"Air"},{"name":"updatedAtFrom","in":"query","description":"UTC Date-time to filter inventory updated after (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter inventory updated after (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"updatedAtTo","in":"query","description":"UTC Date-time to filter inventory updated before (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter inventory updated before (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"assignedEmail","in":"query","description":"Email address of the person to which inventory is assigned. Alternative to personId — cannot be combined with personId.","required":false,"schema":{"type":"string","description":"Email address of the person to which inventory is assigned. Alternative to personId — cannot be combined with personId.","example":"employee@company.com"},"example":"employee@company.com"},{"name":"serialNumber","in":"query","description":"Filter by inventory serial numbers","required":false,"schema":{"type":"array","description":"Filter by inventory serial numbers","items":{"type":"string","description":"Filter by inventory serial numbers"}}},{"name":"vendorSku","in":"query","description":"Filter by vendor SKUs","required":false,"schema":{"type":"array","description":"Filter by vendor SKUs","items":{"type":"string","description":"Filter by vendor SKUs"}}},{"name":"sortBy","in":"query","description":"Field to sort by (product, skuId, createdAt, updatedAt, serialNumber, deployStatus, deployReason, assignee, condition, renewalDate, category, suppliedBy)","required":false,"schema":{"type":"string","description":"Field to sort by (product, skuId, createdAt, updatedAt, serialNumber, deployStatus, deployReason, assignee, condition, renewalDate, category, suppliedBy)","example":"product"},"example":"product"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"ASC"},"example":"ASC"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid filter parameters or deprecated deploy status used","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of inventory items","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Inventory"}}}}}}}},"/api/inventory":{"get":{"tags":["Inventory"],"summary":"List inventory items for the authenticated organization","description":"Returns a paginated list of inventory items owned by the caller's organization. Supports filtering by deploy status, person, office, category, and more. Results are sorted by creation date descending by default. Deprecated deploy statuses (GIFTED, LOCKED, OUT_FOR_REPAIR) are rejected with 400.","operationId":"listInventories_1","parameters":[{"name":"page","in":"query","description":"The page number to request (1 based)","required":false,"schema":{"type":"integer","format":"int32","description":"The page number to request (1 based)","example":1},"example":1},{"name":"size","in":"query","description":"The number of results to return in a page","required":false,"schema":{"type":"integer","format":"int32","description":"The number of results to return in a page","example":10,"maximum":100,"minimum":1},"example":10},{"name":"personId","in":"query","description":"Id of a person to which inventory is assigned","required":false,"schema":{"type":"string","description":"Id of a person to which inventory is assigned","example":"00000000-0000-0000-0000-000000000000"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"warehouseId","in":"query","description":"Id of a warehouse to which inventory is assigned","required":false,"schema":{"type":"string","description":"Id of a warehouse to which inventory is assigned","example":"00000000-0000-0000-0000-000000000000"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"officeId","in":"query","description":"Id of an office to which inventory is assigned","required":false,"schema":{"type":"string","description":"Id of an office to which inventory is assigned","example":"00000000-0000-0000-0000-000000000000"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"categories","in":"query","required":false,"schema":{"type":"array","description":"The code of the categories","items":{"type":"string"}}},{"name":"assignedCountryCode","in":"query","required":false,"schema":{"type":"array","description":"Assigned country/region codes such as DE or EU. Ignored when regional transfer is allowed.","items":{"type":"string"}}},{"name":"deployStatuses","in":"query","required":false,"schema":{"type":"array","description":"The deployment statuses","items":{"type":"string","enum":["ARCHIVED","AVAILABLE","AWAITING_ARRIVAL","DEPLOYED","GIFTED","LOCKED","ON_HOLD","OUT_FOR_REPAIR","UNAVAILABLE","VOIDED"],"example":"DEPLOYED"}}},{"name":"skuIds","in":"query","required":false,"schema":{"type":"array","description":"Ids of SKU","items":{"type":"string","format":"uuid"}}},{"name":"searchString","in":"query","description":"Keyword to search for - This searches the description, the name of the manufacturer, the category, the item's title, and the serial number.","required":false,"schema":{"type":"string","description":"Keyword to search for - This searches the description, the name of the manufacturer, the category, the item's title, and the serial number.","example":"Air"},"example":"Air"},{"name":"updatedAtFrom","in":"query","description":"UTC Date-time to filter inventory updated after (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter inventory updated after (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"updatedAtTo","in":"query","description":"UTC Date-time to filter inventory updated before (ISO-8601 without timezone)","required":false,"schema":{"type":"string","format":"date-time","description":"UTC Date-time to filter inventory updated before (ISO-8601 without timezone)","example":"2007-12-03T10:15:30"},"example":"2007-12-03T10:15:30"},{"name":"assignedEmail","in":"query","description":"Email address of the person to which inventory is assigned. Alternative to personId — cannot be combined with personId.","required":false,"schema":{"type":"string","description":"Email address of the person to which inventory is assigned. Alternative to personId — cannot be combined with personId.","example":"employee@company.com"},"example":"employee@company.com"},{"name":"serialNumber","in":"query","description":"Filter by inventory serial numbers","required":false,"schema":{"type":"array","description":"Filter by inventory serial numbers","items":{"type":"string","description":"Filter by inventory serial numbers"}}},{"name":"vendorSku","in":"query","description":"Filter by vendor SKUs","required":false,"schema":{"type":"array","description":"Filter by vendor SKUs","items":{"type":"string","description":"Filter by vendor SKUs"}}},{"name":"sortBy","in":"query","description":"Field to sort by (product, skuId, createdAt, updatedAt, serialNumber, deployStatus, deployReason, assignee, condition, renewalDate, category, suppliedBy)","required":false,"schema":{"type":"string","description":"Field to sort by (product, skuId, createdAt, updatedAt, serialNumber, deployStatus, deployReason, assignee, condition, renewalDate, category, suppliedBy)","example":"product"},"example":"product"},{"name":"sortDirection","in":"query","description":"Sort direction (ASC, DESC)","required":false,"schema":{"type":"string","description":"Sort direction (ASC, DESC)","example":"ASC"},"example":"ASC"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid filter parameters or deprecated deploy status used","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of inventory items","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Inventory"}}}}}}}},"/api/v1/categories":{"get":{"tags":["Categories"],"summary":"List categories available for asset creation","description":"Returns the list of product categories available for asset creation. Use the category code when creating assets without a specific SKU. Optionally filter by code, name (case-insensitive partial match), or active status.","operationId":"listCategories","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":100,"maximum":100,"minimum":1}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"name","in":"query","required":false,"schema":{"type":"string"}},{"name":"active","in":"query","required":false,"schema":{"type":"boolean","default":true}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Invalid pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDTO"}}}},"403":{"description":"Feature flag is disabled or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/catalog/skus/{skuId}":{"get":{"tags":["Catalog"],"summary":"Get a single catalog SKU by ID","description":"Returns pricing and availability details for a single SKU available to the caller's organization. Returns 404 if the SKU does not exist or is not available to this organization.","operationId":"getOrganizationCatalogSKU","parameters":[{"name":"skuId","in":"path","description":"The unique ID of the SKU to retrieve","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"404":{"description":"SKU not found or not available to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested SKU with pricing information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimplifiedProductItemDTO"}}}}}}},"/api/v1/catalog/skus/{skuId}":{"get":{"tags":["Catalog"],"summary":"Get a single catalog SKU by ID","description":"Returns pricing and availability details for a single SKU available to the caller's organization. Returns 404 if the SKU does not exist or is not available to this organization.","operationId":"getOrganizationCatalogSKU_1","parameters":[{"name":"skuId","in":"path","description":"The unique ID of the SKU to retrieve","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"404":{"description":"SKU not found or not available to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested SKU with pricing information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimplifiedProductItemDTO"}}}}}}},"/api/catalog/skus":{"get":{"tags":["Catalog"],"summary":"List SKUs available in the organization's equipment catalog","description":"Returns a paginated list of SKUs (stock-keeping units) available to the caller's organization for ordering. Each SKU represents a purchasable product variant with pricing and availability information. Optionally filter by category code (e.g. COMPUTER, MONITOR, HEADSET) to narrow results.","operationId":"getOrganizationCatalogSKUs","parameters":[{"name":"page","in":"query","description":"Page number to return (1-based, default: 1)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page (default: 100, max: 100)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32"},"example":10},{"name":"categories","in":"query","description":"Filter by one or more category codes (e.g. COMPUTER, MONITOR)","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid pagination or filter parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of catalog SKUs","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SimplifiedProductItemDTO"}}}}}}}},"/api/v1/catalog/skus":{"get":{"tags":["Catalog"],"summary":"List SKUs available in the organization's equipment catalog","description":"Returns a paginated list of SKUs (stock-keeping units) available to the caller's organization for ordering. Each SKU represents a purchasable product variant with pricing and availability information. Optionally filter by category code (e.g. COMPUTER, MONITOR, HEADSET) to narrow results.","operationId":"getOrganizationCatalogSKUs_1","parameters":[{"name":"page","in":"query","description":"Page number to return (1-based, default: 1)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"size","in":"query","description":"Number of results per page (default: 100, max: 100)","required":false,"allowEmptyValue":true,"schema":{"type":"integer","format":"int32"},"example":10},{"name":"categories","in":"query","description":"Filter by one or more category codes (e.g. COMPUTER, MONITOR)","required":false,"allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid pagination or filter parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of catalog SKUs","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SimplifiedProductItemDTO"}}}}}}}},"/api/v1/carriers":{"get":{"tags":["Shipment"],"summary":"List supported shipment carriers","description":"Returns supported carriers for shipment tracking. You can optionally filter carriers by tracking platform.","operationId":"listShipmentCarriers","parameters":[{"name":"platform","in":"query","description":"Optional tracking platform to filter carriers by. One of: EASYPOST, AFTERSHIP.","required":false,"schema":{"type":"string","enum":["EASYPOST","AFTERSHIP"]},"example":"EASYPOST"}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request — invalid platform parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"List of supported carriers","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CarrierTypeDto"}}}}}}}},"/api/v1/brands":{"get":{"tags":["Brands"],"summary":"List brands available for asset creation","description":"Returns the list of brands available for asset creation. Use the brand code when creating assets with category_code. Optionally filter by code, name (case-insensitive partial match), or active status.","operationId":"listBrands","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":1,"minimum":1}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":100,"maximum":100,"minimum":1}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"name","in":"query","required":false,"schema":{"type":"string"}},{"name":"active","in":"query","required":false,"schema":{"type":"boolean","default":true}}],"responses":{"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Invalid pagination parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Paginated list of brands","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDTO"}}}},"403":{"description":"Feature flag is disabled or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/shipment-notices/{id}":{"get":{"tags":["Shipment Notices"],"summary":"Get a shipment notice order by ID — DEPRECATED, use /api/v1/shipment-notices/{id}","description":"DEPRECATED: returns only one serial number per package item. Use /api/v1/shipment-notices/{id} to receive the full inventories list per item. Returns full details for a single shipment notice order belonging to the caller's organization.","operationId":"getShipmentNotice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Shipment notice order not found or does not belong to the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"The requested shipment notice order (legacy format)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNoticeOrderResponse"}}}},"403":{"description":"Feature not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}},"deprecated":true}},"/api/v1/return-orders/{returnOrderId}":{"delete":{"tags":["Return Orders"],"summary":"Cancel return order","description":"Cancels a return order. Allowed only when status is SUBMITTED or CONFIRMED. Releases inventory back to active state. Honors offboarding-vs-one-off branching.","operationId":"deleteReturnOrder","parameters":[{"name":"returnOrderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Return order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Return order status does not allow cancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Return order cancelled"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/return-orders/{returnOrderId}":{"delete":{"tags":["Return Orders"],"summary":"Cancel return order","description":"Cancels a return order. Allowed only when status is SUBMITTED or CONFIRMED. Releases inventory back to active state. Honors offboarding-vs-one-off branching.","operationId":"deleteReturnOrder_1","parameters":[{"name":"returnOrderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Return order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Return order status does not allow cancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Return order cancelled"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/replacements/{replacementId}":{"delete":{"tags":["Replacements"],"summary":"Cancel a replacement","description":"Cancels a replacement. Allowed only when status is SUBMITTED. Cascades to cancel the associated return order and releases any reserved inventory. Gated by the FBS_2976_PUBLIC_API_ENTITY_MODIFICATION feature flag.","operationId":"deleteReplacement","parameters":[{"name":"replacementId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Replacement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Replacement status does not allow cancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Replacement cancelled"},"403":{"description":"Forbidden (feature disabled or unauthorised)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/v1/replacements/{replacementId}":{"delete":{"tags":["Replacements"],"summary":"Cancel a replacement","description":"Cancels a replacement. Allowed only when status is SUBMITTED. Cascades to cancel the associated return order and releases any reserved inventory. Gated by the FBS_2976_PUBLIC_API_ENTITY_MODIFICATION feature flag.","operationId":"deleteReplacement_1","parameters":[{"name":"replacementId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"404":{"description":"Replacement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Replacement status does not allow cancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"204":{"description":"Replacement cancelled"},"403":{"description":"Forbidden (feature disabled or unauthorised)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}}}}},"/api/inventory/{inventoryId}/tags/{tagId}":{"delete":{"tags":["Inventory"],"summary":"Remove tag from inventory","operationId":"removeTagFromInventory","parameters":[{"name":"inventoryId","in":"path","description":"The Inventory ID to remove the tag from","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},{"name":"tagId","in":"path","description":"The Tag ID to remove","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"404":{"description":"Inventory or Tag not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Tag successfully removed from inventory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryTag"}}}}}}},"/api/v1/inventory/{inventoryId}/tags/{tagId}":{"delete":{"tags":["Inventory"],"summary":"Remove tag from inventory","operationId":"removeTagFromInventory_1","parameters":[{"name":"inventoryId","in":"path","description":"The Inventory ID to remove the tag from","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},{"name":"tagId","in":"path","description":"The Tag ID to remove","required":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"404":{"description":"Inventory or Tag not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicApiHttpErrors"}}}},"200":{"description":"Tag successfully removed from inventory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryTag"}}}}}}}},"components":{"schemas":{"PublicApiError":{"type":"object","properties":{"detail":{"type":"string","description":"Human-readable description of the error","example":"Invalid request"},"source":{"type":"string","description":"Entity or field path that caused the error (for example order, shipmentNotice, or person:email)","example":"request"}},"required":["detail","source"]},"PublicApiHttpErrors":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiError"}}},"required":["errors"]},"Address":{"type":"object","properties":{"country":{"type":"string","description":"The country name component. The value MUST be in ISO 3166-1 \"alpha-2\" code format.","example":"US"},"locality":{"type":"string","description":"The city or locality component.","example":"New York City"},"postalCode":{"type":"string","description":"The zip code or postal code component.","example":"10123"},"region":{"type":"string","description":"The state or region component.","example":"NY"},"streetAddress":{"type":"string","description":"The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information.  This attribute MAY contain newlines. Only the first 2 lines will be used.","example":"123 Sesame Street\nSuite 103"},"primary":{"type":"boolean","description":"When true, the address will be the user's mailing address.","example":true}},"required":["country"]},"Email":{"type":"object","properties":{"value":{"type":"string","description":"Email address. The primary email must match `userName`.","example":"jenny.smith@example.com"},"primary":{"type":"boolean","description":"When true, this is the user's primary email address.","example":true}},"required":["value"]},"FirstbaseUser":{"type":"object","description":"Firstbase SCIM user extension attributes.","properties":{"packageId":{"type":"string","format":"uuid","description":"UUID of the equipment package to assign. If automatic ordering is enabled on the package, Firstbase may create equipment orders when the person is provisioned.","example":"d1b0fd87-5fc9-410c-b641-0b7146896ccd"},"startDate":{"type":"string","description":"Person start date (ISO-8601 date, YYYY-MM-DD). Used for new-joiner scheduling and related onboarding workflows.","example":"2022-02-01"},"status":{"type":"string","description":"Lifecycle status for the person (for example ACTIVE, INVITED, OFFBOARDING).","enum":["INVITED","ACTIVE","INACTIVE","DELETED","OFFBOARDING","CANNOT_REACTIVATE"],"example":"ACTIVE"},"skipUserActivation":{"type":"boolean","description":"When true, creates the person without App User access / Okta login provisioning (ordering and inventory only). When false (default), activates the person as an App User.","example":false},"cpfNumber":{"type":"string","description":"Brazilian CPF tax identifier when required for shipping or compliance in supported regions. Digits only; omit when not applicable.","example":"87456236985"},"accessLevel":{"type":"string","description":"Platform access level. BASIC is a standard employee, ADMIN is a full org admin, ADMIN_READ_ONLY is a read-only org admin. Omitted when the person has no access level.","enum":["BASIC","ADMIN","ADMIN_READ_ONLY"],"example":"BASIC","readOnly":true}},"required":["skipUserActivation"]},"Name":{"type":"object","properties":{"familyName":{"type":"string","description":"Family name / last name of the person.","example":"Smith"},"givenName":{"type":"string","description":"Given name / first name of the person.","example":"Jenny"}},"required":["familyName","givenName"]},"PhoneNumber":{"type":"object","properties":{"value":{"type":"string","description":"Phone number. Prefer E.164 / RFC3966 format (for example `tel:+1-201-555-0123`).","example":"1+555-867-5309"},"primary":{"type":"boolean","description":"When true, this is the user's primary phone number.","example":true}},"required":["value"]},"UserSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"SCIM id of the person (Firstbase person UUID). Read-only on responses.","readOnly":true},"addresses":{"type":"array","description":"A physical mailing address for this user. If multiple addresses are present, the element that will be used as the user's Firstbase address will be selected by the following precedence: type `home` marked as `primary`, the first `home` address, the `primary` address, otherwise the first provided address.","items":{"$ref":"#/components/schemas/Address"}},"userName":{"type":"string","description":"The userName must match the `primary` email address.","example":"jenny.smith@example.com"},"emails":{"type":"array","description":"Email addresses for the user. If multiple addresses are present, the `primary` will be used, otherwise the first element will be the user's Firstbase primary email AND userName.","items":{"$ref":"#/components/schemas/Email"}},"name":{"$ref":"#/components/schemas/Name","description":"The components of the user's name."},"phoneNumbers":{"type":"array","description":"Phone numbers for the user. The value SHOULD be specified according to the format defined in [RFC3966], e.g., 'tel:+1-201-555-0123' If multiple phone numbers are present, the `primary` otherwise the first element will be the user's Firstbase phone number.","items":{"$ref":"#/components/schemas/PhoneNumber"}},"urn:ietf:params:scim:schemas:extension:firstbase:1.0:User":{"$ref":"#/components/schemas/FirstbaseUser","description":"Firstbase onboarding attributes for the user (package, start date, status, CPF, activation)."},"schemas":{"type":"array","description":"The schemas defining the attributes of the resources.","example":["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:firstbase:1.0:User"],"items":{"type":"string"}}},"required":["addresses","emails","id","name","schemas","urn:ietf:params:scim:schemas:extension:firstbase:1.0:User","userName"]},"ErrorSchema":{"type":"object","description":"SCIM error response","properties":{"schemas":{"type":"array","description":"SCIM schema URIs that define this error message","items":{"type":"string"}},"detail":{"type":"string","description":"Human-readable error detail"},"scimType":{"type":"string","description":"SCIM error type (when applicable)"},"status":{"type":"string","description":"HTTP status code for the SCIM error, as a string"}},"required":["detail","schemas","status"]},"ShipmentItemResponse":{"type":"object","description":"Item in a shipment","properties":{"id":{"type":"string","format":"uuid","description":"Package item ID"},"sku_id":{"type":"string","format":"uuid","description":"SKU ID"},"expected_quantity":{"type":"integer","format":"int32","description":"Expected quantity"},"description":{"type":"string","description":"Description"}},"required":["id"]},"ShipmentNoticeResponse":{"type":"object","description":"Shipment notice response","properties":{"id":{"type":"string","format":"uuid","description":"Shipment notice order ID"},"source_type":{"type":"string","description":"Source type","enum":["SUPPLIER","OFFICE"]},"status":{"type":"string","description":"Status","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","NOT_COMPLETED","CANCELLED"]},"condition":{"type":"string","description":"Condition","enum":["NEW","USED"]},"warehouse_id":{"type":"string","format":"uuid","description":"Warehouse ID"},"purchase_order_number":{"type":"string","description":"Purchase order number"},"shipments":{"type":"array","description":"Shipments (packages)","items":{"$ref":"#/components/schemas/ShipmentResponse"}},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"}},"required":["id","shipments"]},"ShipmentResponse":{"type":"object","description":"Shipment (package) in a shipment notice","properties":{"id":{"type":"string","format":"uuid","description":"Package ID"},"shipping_carrier":{"type":"string","description":"Shipping carrier"},"tracking_code":{"type":"string","description":"Tracking code"},"tracking_url":{"type":"string","description":"Tracking URL"},"items":{"type":"array","description":"Items in this shipment","items":{"$ref":"#/components/schemas/ShipmentItemResponse"}}},"required":["id","items"]},"CreateShipmentNoticeRequest":{"type":"object","description":"Request to create a shipment notice — an advance notification that equipment is on its way to a Firstbase warehouse","properties":{"warehouse_id":{"type":"string","format":"uuid","description":"ID of the destination Firstbase warehouse where the equipment will be delivered","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"source_type":{"type":"string","description":"Origin of the shipment: SUPPLIER (from a vendor/manufacturer) or OFFICE (from one of the organization's offices)","enum":["SUPPLIER","OFFICE"],"example":"SUPPLIER"},"condition":{"type":"string","description":"Physical condition of the items being shipped (NEW or USED)","enum":["NEW","USED"],"example":"NEW"},"purchase_order_number":{"type":"string","description":"Purchase order number from the organization's procurement system. Required when source_type is SUPPLIER."},"shipments":{"type":"array","description":"List of individual shipment packages, each with tracking info and item details","items":{"$ref":"#/components/schemas/ShipmentRequest"},"minItems":1}},"required":["condition","shipments","source_type","warehouse_id"]},"ShipmentItemRequest":{"type":"object","description":"A line item within a shipment package, identifying a SKU and how many units are included","properties":{"sku_id":{"type":"string","format":"uuid","description":"ID of the SKU (product variant) being shipped","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"quantity":{"type":"integer","format":"int32","description":"Number of units of this SKU included in the shipment (minimum: 1)","example":1,"minimum":1},"region_id":{"type":"string","format":"uuid","description":"Region ID to associate with this inventory when it arrives; defaults to the organization's default region when omitted"},"description":{"type":"string","description":"Free-text description for generic (non-catalogued) SKUs; required when the SKU does not have a product title in the catalog"}},"required":["quantity","sku_id"]},"ShipmentRequest":{"type":"object","description":"A single shipment package within a shipment notice — one box or consignment with its own tracking code","properties":{"shipping_carrier":{"type":"string","description":"Name of the shipping carrier handling this package (e.g. UPS, FedEx, DHL)","example":"UPS"},"tracking_code":{"type":"string","description":"Carrier tracking number for this package","example":"1Z999AA10123456784"},"items":{"type":"array","description":"Items (SKUs) included in this shipment package","items":{"$ref":"#/components/schemas/ShipmentItemRequest"},"minItems":1}},"required":["items"]},"AddressInfo":{"type":"object","properties":{"addressLine1":{"type":"string","description":"Street address line 1","example":"123 Sesame Street"},"addressLine2":{"type":"string","description":"Street address line 2","example":"Suite 103"},"administrativeArea":{"type":"string","description":"State, province, or county","example":"NY"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"US"},"locality":{"type":"string","description":"City or locality","example":"New York City"},"postalCode":{"type":"string","description":"Postal code or ZIP code","example":"10123"}},"required":["countryCode"]},"DeliverToOfficeInfo":{"type":"object","description":"Office to which the order is delivered","properties":{"id":{"type":"string","format":"uuid","description":"Office ID","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Office name","example":"NYC HQ"},"address":{"$ref":"#/components/schemas/AddressInfo","description":"Office address"}},"required":["id"]},"DeliverToPersonInfo":{"type":"object","description":"Person to whom the order is delivered","properties":{"id":{"type":"string","format":"uuid","description":"Person ID","example":"123e4567-e89b-12d3-a456-426614174000"},"firstName":{"type":"string","description":"First name","example":"Jane"},"lastName":{"type":"string","description":"Last name","example":"Smith"},"email":{"type":"string","description":"Email address","example":"jane.smith@example.com"}},"required":["email","firstName","id","lastName"]},"OfficeRef":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Office ID","example":"016fb454-066b-4ba5-9eca-a2fa14b7e7fc"},"name":{"type":["string","null"],"description":"Office name"}},"required":["id"]},"PublicAPIGetOrderResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Order's ID","example":"123E4567-E89B-12D3-A456-426614174000"},"personId":{"type":"string","format":"uuid","description":"The ID of the Person","example":"d7d0d906-425f-402f-bde1-39031c67c40b"},"officeId":{"type":"string","format":"uuid","description":"The ID of the Office","example":"d7d0d906-425f-402f-bde1-39031c67c40b"},"status":{"type":"string","description":"Order's status","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","ACTIVATED","NONE","APPROVED","AWAITING_FULFILLMENT","ACTION_REQUIRED","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"example":"COMPLETED"},"orderItems":{"type":"array","description":"All order item rows on the order, including lines in terminal states such as CANCELLED. Replacing products via PATCH cancels superseded rows rather than deleting them, so consumers should filter by each item's `status` when they care only about active lines.","items":{"$ref":"#/components/schemas/PublicAPIOrderItemResponse"}},"statusHistory":{"type":"array","description":"Chronological history of status changes","items":{"$ref":"#/components/schemas/StatusHistoryEntry"}},"shippingAddress":{"type":"null","$ref":"#/components/schemas/AddressInfo","description":"Order item's shipping address"},"orderType":{"type":"string","description":"Type of order based on lifecycle context","enum":["ONE_OFF","ONBOARDING","REPLACEMENT"]},"submittedBy":{"type":"string","description":"Name of the person who submitted the order","example":"John S. (Firstbase)"},"approvedBy":{"type":"string","description":"Name of the person who approved the order","example":"Jane Smith"},"approvedAt":{"type":"string","format":"date","description":"Date when the order was approved","example":"2026-02-26"},"deliverToOffice":{"$ref":"#/components/schemas/DeliverToOfficeInfo","description":"Office to which the order is delivered, when different from the assigned office"},"deliverToPerson":{"$ref":"#/components/schemas/DeliverToPersonInfo","description":"Person to whom the order is delivered, when different from the assigned person"},"createdAt":{"type":["string","null"],"format":"date-time","description":"UTC ISO-8601 timestamp when the order was created.","example":"2026-02-26T14:15:22.123Z"},"updatedAt":{"type":["string","null"],"format":"date-time","description":"UTC ISO-8601 timestamp when the order was last updated.","example":"2026-03-15T09:00:00.000Z"},"expectedBy":{"type":["string","null"],"format":"date","description":"Date by which the order is expected to be delivered (calendar date, no time component).","example":"2026-03-10"},"packageSlug":{"type":["string","null"],"description":"Slug of the product package this order was created from, if any.","example":"engineering-onboarding"},"deliveryLocation":{"type":["string","null"],"description":"The order's delivery location type (mirrors the FE Orders 'Delivery location' column, where PERSON is shown as 'Employee'). Derived from `deliverToOffice` / `deliverToPerson`: OFFICE when `deliverToOffice` is set, otherwise PERSON when `deliverToPerson` is set.","enum":["PERSON","OFFICE"]}},"required":["id","orderItems","orderType","status","statusHistory"]},"PublicAPIOrderItemResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Order item's ID","example":"123E4567-E89B-12D3-A456-426614174000"},"skuId":{"type":"string","format":"uuid","description":"SKU ID","example":"123E4567-E89B-12D3-A456-426614174000"},"title":{"type":"string","description":"Product title","example":"iPad Air - Silver, 64GB, WiFi"},"categoryCode":{"type":"string","description":"Product category code","example":"COMPUTER"},"status":{"type":"string","description":"Order item's status","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","ACTIVATED","NONE","APPROVED","AWAITING_FULFILLMENT","ACTION_REQUIRED","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"example":"PROCESSING"},"shipment":{"$ref":"#/components/schemas/PublicAPIOrderItemShipmentResponse","description":"Order item's shipment details"},"statusHistory":{"type":"array","description":"Chronological history of status changes","items":{"$ref":"#/components/schemas/StatusHistoryEntry"}},"fulfillmentMethod":{"type":"string","description":"Fulfill-time actual fulfillment method set by operations when the line is fulfilled (WAREHOUSE or DROPSHIP). Distinct from create-time intendedFulfillmentMethod.","enum":["WAREHOUSE","DROPSHIP"]},"vendorSku":{"type":["string","null"],"description":"Vendor's own SKU identifier. Populated only when the underlying SKU has a vendor SKU on file.","example":"APL-MK183LL/A"},"vendorCode":{"type":["string","null"],"description":"Vendor code of the SKU's vendor. Populated only when the SKU's vendor is known.","example":"APPLE"},"serialNumber":{"type":["string","null"],"description":"Serial number assigned to this order item, if any.","example":"C02XL0AAJG5L"},"justification":{"type":["string","null"],"description":"Justification text recorded for this order item, if any.","example":"Need higher RAM for local development workflows"},"purchaseOrderNumber":{"type":["string","null"],"description":"Regional purchase order number stamped on this order item when applicable.","example":"PO-US-LAPTOPS-001"},"type":{"type":["string","null"],"description":"Order item type (PHYSICAL or SERVICE). Top-level order products are PHYSICAL only; SERVICE warranty lines appear nested under orderedWarrantyItem. Populated when feature flag fbs-4375-one-off-fulfillment-source is on; otherwise null.","enum":["PHYSICAL","SERVICE"]},"intendedFulfillmentMethod":{"type":["string","null"],"description":"Create-time fulfillment intent (WAREHOUSE or DROPSHIP). Distinct from fulfill-time fulfillmentMethod. Populated when feature flag fbs-4375-one-off-fulfillment-source is on; otherwise null.","enum":["WAREHOUSE","DROPSHIP"]},"orderedPricing":{"type":"null","$ref":"#/components/schemas/PublicAPIOrderedPricing","description":"Sticky catalog pricing snapshot when the line was created/modified with DROPSHIP intent. Populated when feature flag fbs-4375-one-off-fulfillment-source is on; otherwise null. Warehouse lines have no sticky money. Null when the line is Firstbase Managed (vendor pricing)."},"discountedPrice":{"type":["number","null"],"description":"Server-computed discounted unit price in major currency units when a catalog discount applies. Populated when feature flag fbs-4375-one-off-fulfillment-source is on; otherwise null. Null when the line is Firstbase Managed (vendor pricing).","example":899.0},"orderedWarrantyItem":{"type":"null","$ref":"#/components/schemas/PublicAPIOrderItemResponse","description":"Nested SERVICE warranty order item created with the PHYSICAL line when catalog warranty pricing applied under DROPSHIP. Nested warranty has no further orderedWarrantyItem. Populated when feature flag fbs-4375-one-off-fulfillment-source is on; otherwise null."},"firstbaseManaged":{"type":["boolean","null"],"description":"True when this procurement (DROPSHIP) line was snapshotted as Firstbase Managed at create/modify. Populated when feature flag fbs-4192-firstbase-managed-regions is on; otherwise null. Warehouse lines are false when the flag is on."},"productGroupId":{"type":["string","null"],"format":"uuid","description":"Product group UUID when this line was expanded from a bundle. Null for standalone SKU lines."},"productGroupComponentId":{"type":["string","null"],"format":"uuid","description":"Product group component UUID for this expanded bundle line. Null for standalone SKU lines."},"productGroupInstanceId":{"type":["string","null"],"format":"uuid","description":"Shared id grouping all SKU lines from the same bundle selection on this order."},"productGroupFriendlyId":{"type":["string","null"],"description":"Snapshot of the bundle friendly id (GRP-*) at order time.","example":"GRP-260914-TEST0001"},"productGroupName":{"type":["string","null"],"description":"Snapshot of the bundle name at order time.","example":"Laptop Bundle"}},"required":["categoryCode","id","skuId","status","statusHistory","title"]},"PublicAPIOrderItemShipmentResponse":{"type":"object","properties":{"trackingUrl":{"type":["string","null"],"description":"The carrier's tracking URL for this shipment. Open in a browser to view live shipment status."},"trackingCode":{"type":"string","description":"Tracking code","example":"1Z00000000"},"carrier":{"type":"string","description":"The carrier name","example":"UPS"},"status":{"type":"string","description":"The current status of the shipment","example":"DELIVERED"},"trackingHistory":{"type":"array","description":"A history of recorded shipment status updates in order of date received","items":{"$ref":"#/components/schemas/PublicAPIOrderItemShipmentStatusDTO"}}}},"PublicAPIOrderItemShipmentStatusDTO":{"type":"object","properties":{"status":{"type":"string","description":"The status of the shipment","example":"IN_TRANSIT"},"timestamp":{"type":"string","format":"date-time","description":"Timestamp at which the event was received"}},"required":["status","timestamp"]},"PublicAPIOrderedPricing":{"type":"object","description":"Sticky catalog pricing snapshot on a person-order item when create-time intent was DROPSHIP. Populated on GET/list when feature flag fbs-4375-one-off-fulfillment-source is on; otherwise null.","properties":{"id":{"type":["string","null"],"format":"uuid","description":"Catalog pricing row id","example":"123E4567-E89B-12D3-A456-426614174000"},"unitPrice":{"type":["number","null"],"description":"Unit price in major currency units","example":999.0},"currencyCode":{"type":["string","null"],"description":"ISO 4217 currency code","example":"USD"}}},"PublicApiPersonRef":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Person ID","example":"016fb454-066b-4ba5-9eca-a2fa14b7e7fc"},"forename":{"type":["string","null"],"description":"Person's forename / first name"},"surname":{"type":["string","null"],"description":"Person's surname / last name"}},"required":["id"]},"ReplacementInfo":{"type":"object","description":"Replacement summary included on return responses","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the replacement"},"order":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse","description":"Replacement order details, when available"},"createdAt":{"type":"string","format":"date","description":"Date the replacement was created"},"status":{"type":"string","description":"Current status of the replacement","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","CANCELLED"]}},"required":["createdAt","id","status"]},"ReturnOrderInfo":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Return order ID","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"personId":{"type":["string","null"],"format":"uuid","description":"Person ID","example":"016fb454-066b-4ba5-9eca-a2fa14b7e7fc"},"supportTicketId":{"type":"integer","format":"int64","description":"Support ticket ID","example":12345},"createdAt":{"type":"string","format":"date","description":"Created date","example":"2025-11-26"},"updatedAt":{"type":"string","format":"date","description":"Updated date","example":"2025-11-26"},"confirmedAtTimestamp":{"type":"string","format":"date-time","description":"Confirmed timestamp (UTC)","example":"2025-11-27T10:15:00Z"},"shippingAddress":{"$ref":"#/components/schemas/AddressInfo","description":"Shipping address"},"status":{"type":"string","description":"Return order status","enum":["PENDING","PROCESSING","COMPLETED","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED"],"example":"CONFIRMED"},"retrievals":{"type":"array","description":"Retrieval methods grouped by type. Always contains 4 entries: PL, RETURN_KIT, INBOUND, NOT_MAPPED","items":{"$ref":"#/components/schemas/ReturnRetrievalMethodInfo"}},"replacement":{"$ref":"#/components/schemas/ReplacementInfo","description":"Replacement order if applicable"},"returnLifecycleType":{"type":"string","description":"Return lifecycle type","enum":["ONE_OFF","OFFBOARDING"],"example":"ONE_OFF"},"submittedBy":{"type":"null","$ref":"#/components/schemas/PublicApiPersonRef","description":"Person who submitted the return order."},"office":{"type":"null","$ref":"#/components/schemas/OfficeRef","description":"Office associated with the return, if any."},"person":{"type":"null","$ref":"#/components/schemas/PublicApiPersonRef","description":"Affected person reference (sibling to legacy personId)."},"deliveryLocation":{"type":["string","null"],"description":"The return's delivery location (mirrors the FE Returns 'Delivery location' column). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.","enum":["FIRSTBASE","OFFICE","MULTIPLE"]}},"required":["id","retrievals"]},"ReturnOrderItemInfo":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Return order item's ID","example":"123E4567-E89B-12D3-A456-426614174000"},"skuId":{"type":"string","format":"uuid","description":"SKU ID","example":"123E4567-E89B-12D3-A456-426614174000"},"title":{"type":"string","description":"Product title","example":"iPad Air - Silver, 64GB, WiFi"},"categoryCode":{"type":"string","description":"Product category code","example":"COMPUTER"},"status":{"type":"string","description":"Order item's status","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","ACTIVATED","NONE","APPROVED","AWAITING_FULFILLMENT","ACTION_REQUIRED","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"example":"PROCESSING"},"shipment":{"$ref":"#/components/schemas/PublicAPIOrderItemShipmentResponse","description":"Order item's shipment details"},"returnReason":{"type":"string","description":"Order item's return reason","enum":["OFFBOARDING","UNKNOWN","OFF_CYCLE","DAMAGED","UPGRADE","STANDARD_LIFECYCLE","PRODUCT_CHANGE","OTHER","LOST_BY_WORKER","LOST_BY_PARTNER","FULFILLMENT_ERROR"]},"inventoryId":{"type":"string","format":"uuid","description":"Order item's inventory id"},"retrievalMethodStatus":{"type":"string","description":"Retrieval method status","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"],"example":"DELIVERED"},"inboundTrackingLink":{"type":"string","description":"Inbound tracking link for return kit","example":"https://tracking.example.com/123456"},"inboundCarrier":{"type":"string","description":"Inbound carrier for return kit","example":"UPS"},"inboundTrackingCode":{"type":"string","description":"Inbound tracking code for return kit","example":"1Z999AA10123456784"},"outboundTrackingLink":{"type":"string","description":"Outbound tracking link for return kit","example":"https://tracking.example.com/789012"},"outboundCarrier":{"type":"string","description":"Outbound carrier for return kit","example":"FedEx"},"outboundTrackingCode":{"type":"string","description":"Outbound tracking code for return kit","example":"1Z999AA10567890123"},"itad":{"type":"boolean","description":"Whether this item was elected for ITAD (IT Asset Disposition)","example":false},"vendorSku":{"type":["string","null"],"description":"Vendor's own SKU identifier.","example":"APL-MK183LL/A"},"vendorCode":{"type":["string","null"],"description":"Vendor short code.","example":"APPLE"},"serialNumber":{"type":["string","null"],"description":"Serial number assigned to the inventory unit, if any."},"holdRequested":{"type":["boolean","null"],"description":"Whether a machine retention hold was requested for this item at return creation. Null when not applicable or enhanced fields are not enabled."}},"required":["categoryCode","id","itad","skuId","status","title"]},"ReturnRetrievalMethodInfo":{"type":"object","description":"Retrieval method with associated return items","properties":{"methodType":{"type":"string","description":"Type of retrieval method","enum":["PL","RETURN_KIT","INBOUND","NOT_MAPPED"],"example":"RETURN_KIT"},"items":{"type":"array","description":"List of return items using this retrieval method. Empty array if no items use this method.","items":{"$ref":"#/components/schemas/ReturnOrderItemInfo"}}},"required":["items","methodType"]},"StatusHistoryEntry":{"type":"object","properties":{"status":{"type":"string","description":"Order status at time of change","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","ACTIVATED","NONE","APPROVED","AWAITING_FULFILLMENT","ACTION_REQUIRED","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"example":"APPROVED"},"timestamp":{"type":"string","format":"date-time","description":"Timestamp of status change in UTC","example":"2023-01-01T12:00:00Z"}},"required":["status","timestamp"]},"CreateAddressRequest":{"type":"object","description":"Shipping or return kit address","properties":{"addressLine1":{"type":"string","description":"Street address line 1","example":"123 Main Street","minLength":1},"addressLine2":{"type":"string","description":"Street address line 2","example":"Apartment B"},"city":{"type":"string","description":"City","example":"San Francisco","minLength":1},"state":{"type":"string","description":"State or province","example":"California"},"zipCode":{"type":"string","description":"Postal / ZIP code","example":"94158","minLength":1},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"US","minLength":1},"phoneNumber":{"type":"string","description":"Phone number","example":"+1-555-123-4567"}},"required":["addressLine1","city","country","zipCode"]},"CreateReturnItemRequest":{"type":"object","description":"An item to include in a return or replacement","properties":{"inventoryId":{"type":"string","format":"uuid","description":"Inventory ID of the item to return. Required if serialNumber is not provided","example":"123e4567-e89b-12d3-a456-426614174000"},"serialNumber":{"type":"string","description":"Serial number of the item to return. Required if inventoryId is not provided","example":"SN-12345"},"returnReason":{"type":"string","description":"Reason for the return. OFFBOARDING is not allowed via API","enum":["OFFBOARDING","UNKNOWN","OFF_CYCLE","DAMAGED","UPGRADE","STANDARD_LIFECYCLE","PRODUCT_CHANGE","OTHER","LOST_BY_WORKER","LOST_BY_PARTNER","FULFILLMENT_ERROR"]},"returnReasonComment":{"type":"string","description":"Additional comment about the return reason"},"returnMethod":{"type":"string","description":"Return method: SHIPMENT (default) or DROP_OFF. DROP_OFF is only allowed for office returns (when officeId is specified). Warehouse returns must use SHIPMENT","enum":["DROP_OFF","SHIPMENT","MULTIPLE"]},"itad":{"type":"boolean","default":false,"description":"Whether to elect this item for ITAD (IT Asset Disposition). Only valid for warehouse returns (not office returns) and ITAD-eligible categories (COMPUTER, MOBILE_PHONE, DRAWING_TABLET, TABLET, EXTERNAL_HDD)."},"holdRequested":{"type":["boolean","null"],"description":"Whether to request a machine retention hold for this item. Only available when this capability is enabled for your organization. When available and the organization's retention policy for the person's region is AD_HOC, set to true to request a hold. Omitted or null is treated as false. Sending this field when the capability is unavailable returns 403."}},"required":["returnMethod","returnReason"]},"CreateReturnRequest":{"type":"object","description":"Request to create a return order","properties":{"personId":{"type":"string","format":"uuid","description":"ID of the person the return is for","example":"123e4567-e89b-12d3-a456-426614174000"},"returnItems":{"type":"array","description":"Items to include in the return","items":{"$ref":"#/components/schemas/CreateReturnItemRequest"},"minItems":1},"returnKitAddress":{"$ref":"#/components/schemas/CreateAddressRequest","description":"Address for the return kit shipment. Required when requestAddressConfirmation is false (the default). Omit only when requestAddressConfirmation is true, in which case the person is prompted to confirm their address before the kit ships."},"officeId":{"type":"string","format":"uuid","description":"Office ID to return equipment to. When provided, returnTo is set to OFFICE and returnMethod is forced to SHIPMENT","example":"123e4567-e89b-12d3-a456-426614174000"},"requestAddressConfirmation":{"type":"boolean","description":"Whether to request address confirmation from the person before shipping the return kit"}},"required":["personId","requestAddressConfirmation","returnItems"]},"PublicAPICreateReplacementResponse":{"type":"object","description":"Response after creating a replacement","properties":{"id":{"type":"string","format":"uuid","description":"Replacement ID"},"orderId":{"type":"string","format":"uuid","description":"ID of the replacement order (new equipment)"},"returnOrderId":{"type":"string","format":"uuid","description":"ID of the return order"},"status":{"type":"string","description":"Current status of the replacement","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","CANCELLED"]}},"required":["id","status"]},"CreateReplacementRequest":{"type":"object","description":"Request to create a replacement (return + new order)","properties":{"personId":{"type":"string","format":"uuid","description":"ID of the person whose equipment is being replaced"},"returnItems":{"type":"array","description":"Items to return as part of the replacement","items":{"$ref":"#/components/schemas/CreateReturnItemRequest"},"minItems":1},"order":{"$ref":"#/components/schemas/ReplacementOrderRequest","description":"The replacement order details (new equipment)"},"returnKitAddress":{"$ref":"#/components/schemas/CreateAddressRequest","description":"Address for the return kit shipment. Required when requestAddressConfirmation is false (the default). Omit only when requestAddressConfirmation is true, in which case the person is prompted to confirm their address before the kit ships. If omitted and requestAddressConfirmation is false, the order's shipping address is used."},"officeId":{"type":"string","format":"uuid","description":"Office ID for office returns. When set, items are returned to the office via SHIPMENT"},"requestAddressConfirmation":{"type":"boolean","description":"Whether to request address confirmation from the person before shipping the return kit"}},"required":["order","personId","requestAddressConfirmation","returnItems"]},"PublicAPISkuInformation":{"type":"object","description":"A SKU (product variant) to include in an order, with optional shipping, condition, and create-time fulfillment intent. Clients send sku id + optional intendedFulfillmentMethod only — do not send pricingId, warrantyPricingId, or discountedPrice. When intendedFulfillmentMethod is DROPSHIP and feature flag fbs-4375-one-off-fulfillment-source is on, the server resolves active catalog pricing, warranty pricing, and discount for the order shipping region. WAREHOUSE has no sticky money and is not hard-rejected when warehouse stock is empty. Procurement (DROPSHIP) is not expeditable.","properties":{"id":{"type":"string","format":"uuid","description":"ID of the SKU to order","example":"123e4567-e89b-12d3-a456-426614174000"},"expeditedShippingOption":{"type":"string","description":"Expedited shipping option for this SKU; null means standard shipping applies","enum":["EXPEDITED_STANDARD"]},"preferredCondition":{"type":"string","description":"Preferred item condition: NEW (new-only) or USED (used preferred). Omit to default to NEW-only preference","enum":["NEW","USED"]},"intendedFulfillmentMethod":{"type":["string","null"],"description":"Create-time fulfillment intent for this line (WAREHOUSE or DROPSHIP). Distinct from fulfill-time fulfillmentMethod on GET responses. Honored when feature flag fbs-4375-one-off-fulfillment-source is on; ignored when the flag is off. Omit/null = legacy create. For DROPSHIP the server resolves catalog pricing/warranty/discount for the shipping region (clients must not send pricing ids). WAREHOUSE maps intent only (no sticky pricing).","enum":["WAREHOUSE","DROPSHIP"]}},"required":["id"]},"ReplacementOrderRequest":{"type":"object","description":"Details of the replacement order (new equipment to ship)","properties":{"skus":{"type":"array","description":"SKUs to order as replacements","items":{"$ref":"#/components/schemas/PublicAPISkuInformation"},"minItems":1},"shippingAddress":{"$ref":"#/components/schemas/CreateAddressRequest","description":"Shipping address for the replacement order. Required when requestAddressConfirmation is false (the default). May be omitted when requestAddressConfirmation is true, in which case the person is prompted to confirm their address before the replacement ships."}},"required":["skus"]},"Package":{"type":"object","description":"An equipment package (onboarding bundle) that can be assigned to a person","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this package","example":"3a68a467-8733-4c8d-a942-16ed7ec33018"},"name":{"type":"string","description":"Display name of the package","example":"The works"},"automaticOrder":{"type":"boolean","description":"When true, an equipment order is placed automatically when a person with this package is onboarded","example":false},"approvalRequired":{"type":"boolean","description":"When true, orders from this package require manager approval before being processed","example":false},"requireJustification":{"type":"boolean","description":"When true, order items in this package require a justification","example":false},"active":{"type":"boolean","description":"Whether this package is currently active. Inactive packages cannot be used for new assignments","example":true},"skuIds":{"type":"array","description":"List of SKU IDs included in this package; null when no SKUs are configured","examples":["3cf416c1-1b0f-4344-9cec-ba9c9fe615c9"],"items":{"type":"string","format":"uuid"}},"assignedTo":{"$ref":"#/components/schemas/PackageAssignedToInformation","description":"People and groups currently assigned to this package"}},"required":["active","approvalRequired","assignedTo","automaticOrder","id","name","requireJustification"]},"PackageAssignedToInformation":{"type":"object","properties":{"people":{"type":"array","description":"List of people assigned to this package. Each entry contains identifying information for a person linked to this package assignment.","examples":["3cf416c1-1b0f-4344-9cec-ba9c9fe615c9"],"items":{"type":"string","format":"uuid"}}}},"Person":{"type":"object","description":"A person (employee) record in Firstbase","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this person","example":"e2bd9633-46b4-4286-85bd-3403a3f17e0f"},"role":{"type":"string","description":"Role of this person within the organization (BASIC = standard employee, ADMIN = org admin)","enum":["BASIC","ADMIN"],"example":"BASIC"},"firstName":{"type":"string","description":"First name of the person","example":"Jenny"},"lastName":{"type":"string","description":"Last name of the person","example":"Smith"},"identityEmail":{"type":"string","description":"Identity email address, used for platform login and notifications","example":"jenny@example.com"},"email":{"type":"string","description":"Primary email address, used for platform login and notifications","example":"jenny@example.com"},"secondaryEmail":{"type":"string","description":"Secondary email address; null when not provided","example":"jenny@secondary.example.com"},"phoneNumber":{"type":"string","description":"Phone number from the person's home address; null when not provided","example":"555-867-5309"},"startDate":{"type":"string","format":"date","description":"Employment start date, used to trigger onboarding timelines","example":"2023-11-22"},"homeAddress":{"$ref":"#/components/schemas/AddressInfo","description":"Home address of the person, used for equipment deliveries"},"package":{"$ref":"#/components/schemas/Package","description":"Equipment package currently assigned to this person; null when no package is assigned"},"status":{"type":"string","description":"Current lifecycle status of the person in Firstbase (e.g. INVITED, ACTIVE, OFFBOARDING)","enum":["INVITED","ACTIVE","INACTIVE","DELETED","OFFBOARDING","CANNOT_REACTIVATE"]},"cpfNumber":{"type":"string","description":"Brazilian CPF tax number; null for non-Brazilian employees","example":"87523654789"},"accessLevel":{"type":"string","description":"Platform access level. BASIC is a standard employee, ADMIN is a full org admin, ADMIN_READ_ONLY is a read-only org admin. Omitted when the person has no access level.","enum":["BASIC","ADMIN","ADMIN_READ_ONLY"],"example":"BASIC","readOnly":true}},"required":["firstName","id","lastName","role","status"]},"OffboardAddressInfo":{"type":"object","properties":{"addressLine1":{"type":"string","description":"Street address line 1","example":"123 Sesame Street"},"addressLine2":{"type":"string","description":"Street address line 2","example":"Suite 103"},"administrativeArea":{"type":"string","description":"the state or county","example":"NY"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"US"},"locality":{"type":"string","description":"the city","example":"New York City"},"postalCode":{"type":"string","description":"the postal code or zip code","example":"10123"},"phoneNumber":{"type":["string","null"],"description":"Phone number for the return shipping address. When omitted, the person's existing phone number is preserved.","example":"555-867-5309"}},"required":["countryCode"]},"OffboardItemToNotReturn":{"type":"object","properties":{"inventoryId":{"type":"string","format":"uuid","description":"Inventory ID NOT being returned."},"deployReason":{"type":"string","description":"Reason this item is not being returned.","enum":["ASSIGNED_TO_ADMIN","AWAITING_INFORMATION","BOUGHT_OUT","CANCELLED_BY_FIRSTBASE","CANCELLED_BY_VENDOR","CHURNED_CUSTOMER","DATA_ERROR","DATA_HOLD","DECOMMISSIONED_BY_EMPLOYER","DECOMMISSIONED_BY_FIRSTBASE","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","NEVER_RETURNED_BY_WORKER","OTHER","OUT_FOR_DESTRUCTION","OUT_FOR_REPAIR","PENDING_BUY_OUT","PENDING_HOLD_RELEASE","RECYCLING_REQUESTED","REQUIRES_CLEANING","REQUIRES_REPAIR","RETURN_IN_PROGRESS","SENT_TO_OFFICE","STAGED_FOR_3RD_PARTY","STOLEN","UNRESPONSIVE_WORKER","UNSUPPORTED_REGION","PERSONAL_DEVICE"]},"deployReasonDetail":{"type":["string","null"],"description":"Free-text detail. Required when deployReason is OTHER. Maximum 35 characters.","maxLength":35,"minLength":0}},"required":["deployReason","inventoryId"]},"OffboardItemToReturn":{"type":"object","properties":{"inventoryId":{"type":"string","format":"uuid","description":"Inventory ID being returned or dropped off at office."},"returnReasonComment":{"type":["string","null"],"description":"Optional free-text comment about the return. Only used for ship return types (SHIP_TO_FIRSTBASE, SHIP_TO_OFFICE). Rejected when non-blank on DROPPED_TO_OFFICE.","maxLength":500,"minLength":0},"itad":{"type":["boolean","null"],"description":"Whether to elect ITAD (IT Asset Disposition) for this item. Only used for ship return types. Not allowed for subscription/HaaS items. Rejected when true on DROPPED_TO_OFFICE."},"holdRequested":{"type":["boolean","null"],"description":"Whether to request a machine retention hold for this item. Only used for ship return types. Only available when this capability is enabled for your organization. When available and the organization's retention policy for the person's region is AD_HOC, set to true to request a hold. Omitted or null is treated as false. Sending this field when the capability is unavailable returns 403. Rejected when true on DROPPED_TO_OFFICE."}},"required":["inventoryId"]},"OffboardPersonRequest":{"type":"object","properties":{"personLastDate":{"type":"string","format":"date","description":"Employee's last working date."},"returnType":{"type":"string","description":"How the equipment will be returned.","enum":["SHIP_TO_FIRSTBASE","SHIP_TO_OFFICE","DROPPED_TO_OFFICE"]},"officeId":{"type":["string","null"],"format":"uuid","description":"Office ID. Required for SHIP_TO_OFFICE and DROPPED_TO_OFFICE return types."},"itemsToReturn":{"type":["array","null"],"description":"Equipment to be returned or dropped off at the office. Behavior depends on returnType: ship paths create a return order; DROPPED_TO_OFFICE assigns inventory to officeId. Every eligible inventory item must appear in exactly one of itemsToReturn or itemsToNotReturn. Must-return (Firstbase-supplied HaaS) items must be listed here.","items":{"$ref":"#/components/schemas/OffboardItemToReturn"}},"itemsToNotReturn":{"type":["array","null"],"description":"Equipment NOT being returned (with deploy reasons). Every eligible inventory item must appear in exactly one of itemsToReturn or itemsToNotReturn.","items":{"$ref":"#/components/schemas/OffboardItemToNotReturn"}},"address":{"type":"null","$ref":"#/components/schemas/OffboardAddressInfo","description":"Confirmed shipping address. Only allowed when addressValidationNeeded=false with a ship return type (SHIP_TO_FIRSTBASE/SHIP_TO_OFFICE) that has itemsToReturn. When supplied it overwrites the person's stored home address and is used for the return order. phoneNumber is optional; when omitted the person's existing phone number is preserved."},"addressValidationNeeded":{"type":"boolean","default":true,"description":"When true (default), employee confirms shipping address before the return kit is sent. When false, the return order is auto-confirmed using the admin-supplied address; if there are no items to return, the person transitions directly to INACTIVE."}},"required":["personLastDate","returnType"]},"PeopleEmailRequest":{"type":"object","description":"Request body for triggering an admin email action to a person","properties":{"emailType":{"type":"string","description":"The type of email action to trigger. RESEND_ACTIVATION: resend activation email to an INVITED person. RESEND_OFFBOARDING: resend the arrange-return email to a person in OFFBOARDING status. SEND_PLATFORM_INVITE: send a platform access invite to an ACTIVE person without a platform account.","enum":["RESEND_ACTIVATION","RESEND_OFFBOARDING","SEND_PLATFORM_INVITE"]}},"required":["emailType"]},"CreatePackageResponse":{"type":"object","description":"Response body after creating a package","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the package","example":"3a68a467-8733-4c8d-a942-16ed7ec33018"},"name":{"type":"string","description":"Display name of the package","example":"Engineering Starter Kit"},"slug":{"type":"string","description":"URL-safe unique identifier for the package","example":"engineering-starter-kit"},"active":{"type":"boolean","description":"Whether the package is active","example":true},"approval_required":{"type":"boolean","description":"When true, orders created from this package require admin approval before fulfillment.","example":false},"require_justification":{"type":"boolean","description":"When true, requesters must provide a justification when ordering from this package.","example":false},"automatic_order":{"type":"boolean","description":"When true, assigning this package can trigger automatic equipment ordering.","example":false},"it_closet":{"type":"boolean","description":"When true, the package is intended for IT closet / office stock.","example":false},"delivery_setting":{"type":"string","description":"Where package equipment should be delivered","enum":["PERSON","OFFICE","FLEXIBLE"],"example":"PERSON"},"note":{"type":"string","description":"Optional note shown with the package","example":"Standard package for new engineering hires"},"default_office_id":{"type":"string","format":"uuid","description":"Default office UUID when delivery targets an office","example":"3a68a467-8733-4c8d-a942-16ed7ec33018"},"sku_ids":{"type":"array","description":"SKU UUIDs included in this package","items":{"type":"string","format":"uuid"}},"rules":{"type":"array","description":"Category quantity rules for the package","items":{"$ref":"#/components/schemas/PackageRuleResponse"}},"number_ordered":{"type":"integer","format":"int32","description":"Count of orders placed against this package","example":0},"number_deployed":{"type":"integer","format":"int32","description":"Count of package assignments that have been deployed","example":0},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the package was created"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the package was last updated"}},"required":["active","approval_required","automatic_order","id","it_closet","name","number_deployed","number_ordered","require_justification","slug"]},"PackageRuleResponse":{"type":"object","description":"A rule within a package","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the rule","example":"3a68a467-8733-4c8d-a942-16ed7ec33018"},"category_code":{"type":"string","description":"Product category code this rule applies to","example":"LAPTOP"},"quantity":{"type":"integer","format":"int32","description":"Number of items allowed or required for this category","example":1},"optional":{"type":"boolean","description":"When true, this category rule is optional","example":false},"allowed_product_ids":{"type":"array","description":"Product UUIDs allowed by this rule; empty means no product restriction","items":{"type":"string","format":"uuid"}}},"required":["category_code","id","optional","quantity"]},"CreatePackageRequest":{"type":"object","description":"Request body for creating a package","properties":{"name":{"type":"string","description":"Display name of the package","example":"Engineering Starter Kit","minLength":1},"approval_required":{"type":"boolean","description":"When true, orders created from this package require admin approval before fulfillment.","example":false},"require_justification":{"type":"boolean","description":"When true, requesters must provide a justification when ordering from this package.","example":false},"automatic_order":{"type":"boolean","description":"When true, assigning this package to a person can trigger automatic equipment ordering.","example":false},"default_office_id":{"type":"string","format":"uuid","description":"Default office UUID used when the package delivery setting targets an office.","example":"3a68a467-8733-4c8d-a942-16ed7ec33018"},"delivery_setting":{"type":"string","description":"Where package equipment should be delivered (for example PERSON or OFFICE).","enum":["PERSON","OFFICE","FLEXIBLE"],"example":"PERSON"},"note":{"type":"string","description":"Optional note shown with the package.","example":"Standard package for new engineering hires"},"sku_ids":{"type":"array","description":"SKU UUIDs included in this package.","items":{"type":"string","format":"uuid"}},"sku_lines":{"type":"array","description":"Per-SKU region lines for the package (vendorCode, vendorSku, regionIds).","items":{"$ref":"#/components/schemas/PackageSkuLineRequest"}},"rules":{"type":"array","description":"Category quantity rules for the package.","items":{"$ref":"#/components/schemas/PackageRuleRequest"}}},"required":["approval_required","automatic_order","delivery_setting","name","require_justification"]},"PackageRuleRequest":{"type":"object","description":"A rule for a package","properties":{"category_code":{"type":"string","description":"Product category code this rule applies to.","example":"LAPTOP","minLength":1},"quantity":{"type":"integer","format":"int32","description":"Number of items allowed or required for this category.","example":1},"optional":{"type":"boolean","description":"When true, this category rule is optional for people on the package.","example":false}},"required":["category_code","optional","quantity"]},"PackageSkuLineRequest":{"type":"object","description":"Per-SKU region selection for a package line","properties":{"vendor_code":{"type":"string","description":"Vendor code for the SKU.","example":"DELL","minLength":1},"vendor_sku":{"type":"string","description":"Vendor SKU identifier.","example":"LAT-7420","minLength":1},"region_ids":{"type":"array","description":"Region UUIDs selected for this SKU line.","items":{"type":"string","format":"uuid"},"minItems":1}},"required":["region_ids","vendor_code","vendor_sku"]},"PublicAPIApproveOrderRequest":{"type":"object","properties":{"approvedByPersonId":{"type":"string","format":"uuid","description":"Optional person ID to record as the approver","example":"d7d0d906-425f-402f-bde1-39031c67c40b"}}},"PublicAPICreateOrderResponse":{"type":"object","description":"Response after creating an order","properties":{"orderId":{"type":"string","format":"uuid","description":"UUID of the created order"},"itemIds":{"type":"array","description":"UUIDs of PHYSICAL order line items created with this order. SERVICE warranty lines are omitted; they appear nested under orderedWarrantyItem on GET.","items":{"type":"string","format":"uuid"}}},"required":["itemIds","orderId"]},"PublicAPICreateOrderRequest":{"type":"object","description":"Request body for creating a new order. Either `personId` or `officeId` must be provided, but not both.","properties":{"shippingAddress":{"type":"null","$ref":"#/components/schemas/PublicAPICreateShippingAddress","description":"The shipping address for the order. If not provided, it will be auto-resolved from the deliverToOffice address, the person's address (personId), or the office's address (officeId) — in that priority order."},"personId":{"type":["string","null"],"format":"uuid","description":"The ID of the person receiving the order. Either this or `officeId` must be set, but not both.","example":"123e4567-e89b-12d3-a456-426614174000"},"officeId":{"type":["string","null"],"format":"uuid","description":"The ID of the office receiving the order. Either this or `personId` must be set, but not both.","example":"123e4567-e89b-12d3-a456-426614174001"},"deliverToPersonId":{"type":["string","null"],"format":"uuid","description":"The ID of the person to whom the order should be delivered. Used to auto-resolve the shipping address when shippingAddress is not provided.","example":"123e4567-e89b-12d3-a456-426614174002"},"deliverToOfficeId":{"type":["string","null"],"format":"uuid","description":"The ID of the office to which the order should be delivered. Used to auto-resolve the shipping address when shippingAddress is not provided.","example":"123e4567-e89b-12d3-a456-426614174003"},"skus":{"type":"array","description":"A list of SKUs (items) to include in the order. At least one of `skus` or `productGroupIds` must be non-empty.","items":{"$ref":"#/components/schemas/PublicAPISkuInformation"}},"productGroupIds":{"type":"array","description":"Product-group bundle UUIDs to order. Each expands to SKU lines with the same fulfillability rules as the admin UI (required unfulfillable blocks; optional drops). At least one of `skus` or `productGroupIds` must be non-empty. Requires the product-groups-bundles feature flag.","items":{"type":"string","format":"uuid"}}}},"PublicAPICreateShippingAddress":{"type":"object","description":"Shipping address","properties":{"addressLine1":{"type":"string","description":"The primary line of the address (e.g., house number and street name)","example":"123 Main Street"},"addressLine2":{"type":["string","null"],"description":"Additional address information (e.g., apartment or suite number)","example":"Apartment B"},"administrativeArea":{"type":["string","null"],"description":"The state, province, or region within the country","example":"California"},"countryCode":{"type":"string","description":"A two-letter ISO 3166-1 alpha-2 code representing the country","example":"US"},"dependentLocality":{"type":["string","null"],"description":"A smaller subdivision within the locality, often used for neighborhoods or districts","example":"Mission Bay"},"locality":{"type":["string","null"],"description":"The city or town within the administrative area","example":"San Francisco"},"postalCode":{"type":["string","null"],"description":"The ZIP code or equivalent postal code","example":"94158"},"sortingCode":{"type":["string","null"],"description":"A code used for routing or sorting mail, often specific to postal systems.","example":"94158-1234"},"phoneNumber":{"type":["string","null"],"description":"A contact phone number, including the international dialing code","example":"+1-415-555-1234"}},"required":["countryCode"]},"PublicAPISendReminderRequest":{"type":"object","description":"Request body for sending a new joiner reminder email","properties":{"senderPersonId":{"type":["string","null"],"format":"uuid","description":"Optional person ID of the sender for audit purposes. When omitted, sent_by_person_id is recorded as null (triggered via API)."}}},"ITADRequest":{"type":"object","description":"An ITAD (IT Asset Disposition) request","properties":{"id":{"type":"string","format":"uuid","description":"Unique request ID","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"status":{"type":"string","description":"Current request status","enum":["PENDING_DATA_DESTRUCTION","REQUIRES_ACTION","AWAITING_RECHECK","PENDING_SETTLEMENT","COMPLETED","CANCELLED"],"example":"PENDING_DATA_DESTRUCTION"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the request was created"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when the request was completed"},"cancelledAt":{"type":"string","format":"date-time","description":"Timestamp when the request was cancelled"},"totalEstimatedResaleValue":{"type":"number","description":"Total estimated resale value of all items","example":2500.0},"totalResaleValue":{"type":"number","description":"Total actual resale value of all items","example":2300.0},"submittedVia":{"type":"string","description":"How the request was submitted","enum":["ASSETS_PAGE","ITAD_CENTER","RETURN"],"example":"ITAD_CENTER"},"createdByActor":{"type":"string","description":"Actor who created the request","enum":["CUSTOMER","OPS"],"example":"CUSTOMER"},"warehouseId":{"type":"string","format":"uuid","description":"ID of the warehouse","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"},"warehouseName":{"type":"string","description":"Name of the warehouse","example":"US East Warehouse"},"organizationId":{"type":"string","format":"uuid","description":"ID of the organization","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"},"organizationName":{"type":"string","description":"Name of the organization","example":"Acme Corp"},"createdById":{"type":"string","format":"uuid","description":"ID of the person who created the request","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"},"createdByName":{"type":"string","description":"Name of the person who created the request","example":"John Doe"},"lotCodDocumentId":{"type":"string","format":"uuid","description":"Lot Certificate of Destruction document ID"},"lotCodUploadedAt":{"type":"string","format":"date-time","description":"Timestamp when the lot CoD was uploaded"},"settlementReportDocumentId":{"type":"string","format":"uuid","description":"Settlement report document ID"},"settlementReportGeneratedAt":{"type":"string","format":"date-time","description":"Timestamp when the settlement report was generated"},"parentItadRequestId":{"type":"string","format":"uuid","description":"Parent ITAD request ID for multi-warehouse bulk submissions"},"items":{"type":"array","description":"Items in this request (included in detail responses only)","items":{"$ref":"#/components/schemas/ITADRequestItem"}}},"required":["createdByActor","id","status","submittedVia"]},"ITADRequestItem":{"type":"object","description":"An item within an ITAD request","properties":{"id":{"type":"string","format":"uuid","description":"Unique item ID","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"inventoryId":{"type":"string","format":"uuid","description":"ID of the inventory asset","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"},"serialNumber":{"type":"string","description":"Serial number of the asset","example":"C02X1234ABCD"},"skuTitle":{"type":"string","description":"Product title of the SKU","example":"MacBook Pro 14\" M2"},"categoryCode":{"type":"string","description":"Category code of the SKU","example":"COMPUTER"},"estimatedResaleValue":{"type":"number","description":"Estimated resale value","example":450.0},"resaleValue":{"type":"number","description":"Actual resale value","example":420.0},"estimatedMaxCreditValueAtRequest":{"type":"number","description":"Estimated max credit value at time of request","example":500.0},"rmsStatus":{"type":"string","description":"RMS enrollment status","enum":["NOT_ENROLLED","UNENROLLMENT_REQUIRED","AWAITING_RECHECK","CLEARED"],"example":"NOT_ENROLLED"},"status":{"type":"string","description":"Item status","enum":["PENDING","ENQUEUED","DATA_DESTRUCTION_COMPLETED","SETTLED","CANCELLED"],"example":"PENDING"},"settledAmount":{"type":"number","description":"Settled amount after disposition","example":400.0},"grossSaleAmount":{"type":"number","description":"Gross sale amount","example":410.0},"currencyCode":{"type":"string","description":"Currency code for monetary values","example":"USD"},"cancelledAt":{"type":"string","format":"date-time","description":"Timestamp when the item was cancelled"}},"required":["id"]},"CreateITADRequestsRequest":{"type":"object","description":"Request body to create ITAD requests","properties":{"inventoryIds":{"type":"array","description":"List of inventory IDs to include in the ITAD request(s). Items will be grouped by warehouse.","items":{"type":"string","format":"uuid"},"minItems":1},"createdById":{"type":"string","format":"uuid","description":"ID of the person creating the request (must belong to the organization)","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"}},"required":["createdById","inventoryIds"]},"InventoryTag":{"type":"object","description":"A label tag associated with an inventory item, used for grouping and filtering","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this tag","example":"8e0caa73-cc71-4aa4-88eb-fca494de8e20"},"label":{"type":"string","description":"Display label for the tag","example":"Engineering"}},"required":["id","label"]},"PublicAPIAddTagsRequest":{"type":"object","description":"Request body for adding tags to an inventory item. Contains the list of tags to attach.","properties":{"labels":{"type":"array","description":"Set of labels to be added as tags","examples":["Tag 1","Tag 2"],"items":{"type":"string"},"uniqueItems":true}},"required":["labels"]},"InventoryOrderInventoryResponse":{"type":"object","description":"Inventory information for a shipment item","properties":{"id":{"type":"string","format":"uuid","description":"Inventory ID","example":"123E4567-E89B-12D3-A456-426614174000"},"serialNumber":{"type":"string","description":"Serial number","example":"SN123456789"},"deployStatus":{"type":"string","description":"Deploy status","enum":["ARCHIVED","AVAILABLE","AWAITING_ARRIVAL","DEPLOYED","GIFTED","LOCKED","ON_HOLD","OUT_FOR_REPAIR","UNAVAILABLE","VOIDED"],"example":"DEPLOYED"},"warehouse":{"$ref":"#/components/schemas/WarehouseInfo","description":"Warehouse name","example":"Main Warehouse"}},"required":["deployStatus","id"]},"InventoryOrderItemReference":{"type":"object","description":"Reference to inventory order item","properties":{"id":{"type":"string","format":"uuid","description":"Inventory order item ID","example":"123E4567-E89B-12D3-A456-426614174000"}},"required":["id"]},"InventoryOrderItemResponse":{"type":"object","description":"Inventory order item information","properties":{"id":{"type":"string","format":"uuid","description":"Order item ID","example":"123E4567-E89B-12D3-A456-426614174000"},"status":{"type":"string","description":"Order item status","enum":["ACTIVATED","ARRIVED_AT_PROCESSING_FACILITY","CANCELLED","DELIVERY_EXCEPTION","ORDERED","OUT_FOR_DELIVERY","PARTIALLY_ACTIVATED","PARTIALLY_RECEIVED","PARTIALLY_SHIPPED","PENDING","RECEIVED","SHIPPED","ACTION_REQUIRED"],"example":"RECEIVED"},"sku":{"$ref":"#/components/schemas/SkuReference","description":"SKU ID","example":"123E4567-E89B-12D3-A456-426614174000"},"pricing":{"type":"null","$ref":"#/components/schemas/PricingInfo","description":"Pricing information. Null when the parent inventory order is Firstbase Managed (vendor pricing)."},"quantity":{"type":"integer","format":"int32","description":"Quantity","example":2},"discountedPrice":{"type":["number","null"],"description":"Discounted price. Null when the parent inventory order is Firstbase Managed (vendor pricing).","example":999.0},"warranty":{"$ref":"#/components/schemas/InventoryOrderItemResponse","description":"Warranty item if this is a physical item with warranty"},"type":{"type":"string","description":"Item type","enum":["PHYSICAL","SERVICE"],"example":"PHYSICAL"},"expectedShipDate":{"type":"string","format":"date","description":"Expected ship date","example":"2026-01-20"}},"required":["id","quantity","sku","status","type"]},"InventoryOrderResponse":{"type":"object","description":"Inventory order information","properties":{"id":{"type":"string","format":"uuid","description":"Order ID","example":"123E4567-E89B-12D3-A456-426614174000"},"friendlyOrderId":{"type":["string","null"],"description":"Human-readable friendly order ID (order number shown to customers). Null for orders created before this field was populated.","example":"ORD-000123"},"status":{"type":"string","description":"Order status","enum":["CANCELLED","COMPLETE","ORDERED","PARTIALLY_RECEIVED","PROCESSING","RECEIVED","SHIPPED","SUBMITTED"],"example":"PROCESSING"},"warehouse":{"$ref":"#/components/schemas/WarehouseReference","description":"Warehouse information"},"customerPoNumber":{"type":"string","description":"Customer PO number","example":"PO-12345"},"reason":{"type":"string","description":"Order reason","enum":["ONE_OFF","RESTOCK"],"example":"ONE_OFF"},"billingType":{"type":"string","description":"Billing type","enum":["SUBSCRIPTION","PURCHASED"],"example":"SUBSCRIPTION"},"firstbaseManaged":{"type":"boolean","description":"Whether this order is Firstbase Managed (snapshotted at create from region FM config and firstbase supplied). When true, item and warranty pricing is omitted (vendor pricing).","example":false},"submittedBy":{"$ref":"#/components/schemas/PersonReference","description":"Person who submitted the order"},"inventoryOrderItems":{"type":"array","description":"Inventory order items","items":{"$ref":"#/components/schemas/InventoryOrderItemResponse"}},"inventoryOrderShipments":{"type":"array","description":"Inventory order shipments","items":{"$ref":"#/components/schemas/InventoryOrderShipmentResponse"}},"createdAt":{"type":["string","null"],"format":"date-time","description":"UTC ISO-8601 timestamp when the inventory order was created.","example":"2026-02-26T14:15:22.123Z"},"updatedAt":{"type":["string","null"],"format":"date-time","description":"UTC ISO-8601 timestamp when the inventory order was last updated.","example":"2026-03-15T09:00:00.000Z"},"expectedShipDate":{"type":["string","null"],"format":"date","description":"Date by which the inventory order is expected to ship (calendar date, no time component).","example":"2026-03-10"}},"required":["firstbaseManaged","id","inventoryOrderItems","inventoryOrderShipments","reason","status","warehouse"]},"InventoryOrderShipmentItemResponse":{"type":"object","description":"Shipment item information","properties":{"id":{"type":"string","format":"uuid","description":"Shipment item ID","example":"123E4567-E89B-12D3-A456-426614174000"},"inventoryOrderItem":{"$ref":"#/components/schemas/InventoryOrderItemReference","description":"Inventory order item ID","example":"123E4567-E89B-12D3-A456-426614174000"},"quantity":{"type":"integer","format":"int32","description":"Quantity","example":2},"status":{"type":"string","description":"Shipment item status","enum":["ARRIVED_AT_PROCESSING_FACILITY","CANCELLED","DELIVERY_EXCEPTION","ORDERED","OUT_FOR_DELIVERY","RECEIVED","SHIPPED"],"example":"RECEIVED"},"inventories":{"type":"array","description":"Inventories associated with this shipment item","items":{"$ref":"#/components/schemas/InventoryOrderInventoryResponse"}}},"required":["id","inventories","inventoryOrderItem","quantity","status"]},"InventoryOrderShipmentResponse":{"type":"object","description":"Shipment information for an inventory order","properties":{"id":{"type":"string","format":"uuid","description":"Shipment ID","example":"123E4567-E89B-12D3-A456-426614174000"},"status":{"type":"string","description":"Shipment status","enum":["ARRIVED_AT_PROCESSING_FACILITY","CANCELLED","DELIVERY_EXCEPTION","OUT_FOR_DELIVERY","PARTIALLY_RECEIVED","PENDING","RECEIVED","SHIPPED"],"example":"SHIPPED"},"shippingCarrier":{"type":"string","description":"Shipping carrier","example":"UPS"},"trackingCode":{"type":"string","description":"Tracking code","example":"1Z00000000"},"trackingUrl":{"type":"string","description":"Tracking URL","example":"https://tracking.example.com/1Z00000000"},"trackingStatus":{"type":"string","description":"Tracking status","enum":["DELIVERED","EXCEPTION","IN_TRANSIT","OUT_FOR_DELIVERY","PRE_TRANSIT"],"example":"IN_TRANSIT"},"trackingShipmentId":{"type":"string","format":"uuid","description":"Tracking shipment ID","example":"123E4567-E89B-12D3-A456-426614174000"},"estimatedDeliveryDate":{"type":"string","format":"date","description":"Estimated delivery date","example":"2024-01-15"},"etaStart":{"type":"string","format":"date","description":"Estimated delivery start date from tracking provider","example":"2024-01-14"},"etaEnd":{"type":"string","format":"date","description":"Estimated delivery end date from tracking provider","example":"2024-01-16"},"inventoryOrderShipmentItems":{"type":"array","description":"Shipment items","items":{"$ref":"#/components/schemas/InventoryOrderShipmentItemResponse"}}},"required":["id","inventoryOrderShipmentItems","status"]},"PersonReference":{"type":"object","description":"Reference to person","properties":{"id":{"type":"string","format":"uuid","description":"Person ID","example":"123E4567-E89B-12D3-A456-426614174000"},"forename":{"type":["string","null"],"description":"Person's given/first name.","example":"Jane"},"surname":{"type":["string","null"],"description":"Person's surname/last name.","example":"Doe"}},"required":["id"]},"PricingInfo":{"type":"object","description":"Pricing information for an inventory order item","properties":{"id":{"type":"string","format":"uuid","description":"Pricing ID","example":"123E4567-E89B-12D3-A456-426614174000"},"price":{"type":["integer","null"],"format":"int64","deprecated":true,"description":"Price in cents (deprecated, use unitPrice). Null when the parent inventory order is Firstbase Managed (vendor pricing).","example":99900},"unitPrice":{"type":["number","null"],"description":"Unit price in major currency units. Null when the parent inventory order is Firstbase Managed (vendor pricing).","example":999.0}}},"SkuReference":{"type":"object","description":"Reference to SKU","properties":{"id":{"type":"string","format":"uuid","description":"SKU ID","example":"123E4567-E89B-12D3-A456-426614174000"},"vendorSku":{"type":["string","null"],"description":"Vendor's own SKU identifier. Populated only when the SKU has a vendor SKU on file.","example":"APL-MK183LL/A"},"vendorCode":{"type":["string","null"],"description":"Vendor code of the SKU's vendor. Populated only when the SKU's vendor is known.","example":"APPLE"},"categoryCode":{"type":["string","null"],"description":"Category code of the SKU's category. Populated only when the SKU's category is known.","example":"LAPTOP"},"productTitle":{"type":["string","null"],"description":"Product title from the SKU's embedded SKU information.","example":"MacBook Pro 14-inch"}},"required":["id"]},"WarehouseInfo":{"type":"object","description":"Warehouse information","properties":{"name":{"type":"string","description":"Warehouse name","example":"Main Warehouse"}},"required":["name"]},"WarehouseReference":{"type":"object","description":"Reference to warehouse","properties":{"id":{"type":"string","format":"uuid","description":"Warehouse ID","example":"123E4567-E89B-12D3-A456-426614174000"},"name":{"type":["string","null"],"description":"Warehouse display name.","example":"SF Main Warehouse"}},"required":["id"]},"CreateInventoryOrderItemRequest":{"type":"object","description":"An item to include in an inventory order","properties":{"skuId":{"type":"string","format":"uuid","description":"SKU ID of the product to order"},"quantity":{"type":"integer","format":"int32","description":"Quantity to order","example":1,"minimum":1}},"required":["quantity","skuId"]},"CreateInventoryOrderRequest":{"type":"object","description":"Request to create an inventory order","properties":{"warehouseId":{"type":"string","format":"uuid","description":"Warehouse ID where the inventory will be sent"},"regionId":{"type":"string","format":"uuid","description":"Region ID. Required when the organization uses multi-entity"},"items":{"type":"array","description":"Items to include in the inventory order","items":{"$ref":"#/components/schemas/CreateInventoryOrderItemRequest"},"maxItems":100,"minItems":0},"billingType":{"type":"string","description":"Billing type. Required for HAAS organizations (SUBSCRIPTION or PURCHASED). Non-HAAS organizations default to PURCHASED and cannot use SUBSCRIPTION","enum":["SUBSCRIPTION","PURCHASED"]},"firstbaseSupplied":{"type":"boolean","description":"Whether Firstbase supplies the equipment. Defaults to true","example":true},"trackingNumber":{"type":"string","description":"Tracking number for the shipment","maxLength":255,"minLength":0},"notes":{"type":"string","description":"Additional notes for the order","maxLength":1000,"minLength":0},"expectedShipDate":{"type":"string","format":"date","description":"Expected ship date (ISO-8601)","example":"2026-04-01"},"customerPoNumber":{"type":"string","description":"Customer PO number","maxLength":255,"minLength":0}},"required":["items","warehouseId"]},"InventoryLevelResponse":{"type":"object","description":"Inventory level configuration with current stock details for a specific SKU, warehouse, and region","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this inventory level configuration","example":"123e4567-e89b-12d3-a456-426614174000"},"skuId":{"type":"string","format":"uuid","description":"ID of the SKU whose stock level this configuration controls","example":"123e4567-e89b-12d3-a456-426614174000"},"warehouseId":{"type":"string","format":"uuid","description":"ID of the warehouse where this inventory level applies","example":"123e4567-e89b-12d3-a456-426614174000"},"regionId":{"type":"string","format":"uuid","description":"ID of the region scope for this inventory level; null means the organization's default region","example":"123e4567-e89b-12d3-a456-426614174000"},"minQuantity":{"type":"integer","format":"int32","description":"Minimum quantity threshold","example":5},"maxQuantity":{"type":"integer","format":"int32","description":"Maximum quantity threshold","example":20},"includeUsed":{"type":"boolean","description":"Whether used inventory is included in stock calculations"},"autoCreate":{"type":"boolean","description":"Whether inventory orders are automatically created when stock is low"},"active":{"type":"boolean","description":"Whether this inventory level is active"},"customerPoNumber":{"type":"string","description":"Optional customer PO number copied to restock orders created from this level","example":"PO-12345"},"stockDetails":{"$ref":"#/components/schemas/StockDetails","description":"Current stock details for this inventory level"},"createdInventoryOrderId":{"type":"string","format":"uuid","description":"Inventory order id created by autoCreate; null when no restock was triggered.","example":"123E4567-E89B-12D3-A456-426614174000"}},"required":["active","autoCreate","id","includeUsed","maxQuantity","minQuantity","skuId","stockDetails","warehouseId"]},"StockDetails":{"type":"object","description":"Current stock availability details","properties":{"newInventories":{"type":"integer","format":"int32","description":"Count of new-condition inventory items available","example":12},"usedInventories":{"type":"integer","format":"int32","description":"Count of used-condition inventory items available","example":3},"pendingInventoryOrders":{"type":"integer","format":"int32","description":"Count of pending inventory order items","example":2},"totalAvailable":{"type":"integer","format":"int32","description":"Total effective available stock (new + pending, plus used if includeUsed)","example":14},"totalItemsToOrder":{"type":"integer","format":"int32","description":"Number of items to order to reach max level","example":6}},"required":["newInventories","pendingInventoryOrders","totalAvailable","totalItemsToOrder","usedInventories"]},"CreateInventoryLevelRequest":{"type":"object","description":"Request to create an inventory level configuration","properties":{"skuId":{"type":"string","format":"uuid","description":"ID of the SKU to set inventory levels for","example":"123e4567-e89b-12d3-a456-426614174000"},"warehouseId":{"type":"string","format":"uuid","description":"ID of the warehouse","example":"123e4567-e89b-12d3-a456-426614174000"},"minQuantity":{"type":"integer","format":"int32","description":"Minimum quantity threshold","example":5,"minimum":1},"maxQuantity":{"type":"integer","format":"int32","description":"Maximum quantity threshold","example":20,"minimum":1},"regionId":{"type":"string","format":"uuid","description":"ID of the region (optional; uses org default when not provided)","example":"123e4567-e89b-12d3-a456-426614174000"},"includeUsed":{"type":"boolean","description":"Whether to include used inventory in stock calculations","example":false},"autoCreate":{"type":"boolean","description":"Whether to automatically create inventory orders when stock is low","example":false},"customerPoNumber":{"type":"string","description":"Customer purchase order number to apply to restock orders created from this level","example":"PO-12345"}},"required":["autoCreate","includeUsed","maxQuantity","minQuantity","skuId","warehouseId"]},"AssetAppleBusiness":{"type":"object","description":"Apple Business Manager assignment status","properties":{"assignment_status":{"type":"string","description":"Whether the device is assigned in Apple Business Manager","enum":["ASSIGNED","NOT_ASSIGNED"],"example":"ASSIGNED"},"last_sync_timestamp":{"type":["string","null"],"format":"date-time","description":"UTC timestamp of the last successful ABM sync; null when never synced","example":"2026-07-01T12:00:00Z"},"next_sync_timestamp":{"type":"string","format":"date-time","description":"UTC timestamp of the next scheduled ABM full sync","example":"2026-07-02T02:00:00Z"}},"required":["assignment_status","next_sync_timestamp"]},"AssetResponse":{"type":"object","description":"Newly created inventory asset item response","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the created inventory item","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"sku_id":{"type":"string","format":"uuid","description":"ID of the SKU (product variant) this item is associated with; null for custom/generic assets","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"brand_code":{"type":"string","description":"Brand code of the SKU vendor; null when the asset has no associated SKU vendor","example":"APPLE_US"},"serial_number":{"type":"string","description":"Hardware serial number of the device; null when not provided at creation","example":"C02ZX1ABCDEF"},"condition":{"type":"string","description":"Physical condition of the item at creation time (NEW or USED)","enum":["NEW","USED_LIKE_NEW","USED_GOOD","USED_FAIR","USED","USED_POOR","UNUSABLE"],"example":"NEW"},"deploy_status":{"type":"string","description":"Current lifecycle state of the item after creation (typically DEPLOYED when assigned to a person, AVAILABLE when assigned to an office)","enum":["ARCHIVED","AVAILABLE","AWAITING_ARRIVAL","DEPLOYED","GIFTED","LOCKED","ON_HOLD","OUT_FOR_REPAIR","UNAVAILABLE","VOIDED"],"example":"DEPLOYED"},"description":{"type":"string","description":"Free-text product description; populated for custom/generic SKUs when sku_id is null","example":"MacBook Pro 14\" M3"},"renewal_date":{"type":"string","format":"date","description":"Date when this item is scheduled for renewal or replacement","example":"2027-01-15"},"person_id":{"type":"string","format":"uuid","description":"ID of the person this item is assigned to; null when assigned to an office","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"office_id":{"type":"string","format":"uuid","description":"ID of the office this item is assigned to; null when assigned to a person","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"created_at":{"type":"string","format":"date-time","description":"Timestamp (UTC) when this inventory item was created","example":"2024-01-15T10:30:00Z"},"apple_business":{"type":"null","$ref":"#/components/schemas/AssetAppleBusiness","description":"Apple Business Manager assignment for serialized Apple assets. Omitted for non-Apple or non-serialized items."}},"required":["id"]},"CreateAssetRequest":{"type":"object","description":"Request to create an asset (inventory item)","properties":{"sku_id":{"type":"string","format":"uuid","description":"SKU ID for known products. Mutually exclusive with category_code+description.","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"category_code":{"type":"string","description":"Category code for custom/legacy products. Mutually exclusive with sku_id.","example":"LAPTOP"},"brand_code":{"type":"string","description":"Brand code. Optional, used with category_code. Accepts legacy vendor_code.","example":"APPLE"},"brand_id":{"type":"string","format":"uuid","description":"Brand ID. Optional alternative to brand_code. Accepts legacy vendor_id.","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"description":{"type":"string","description":"Product description. Required when category_code is provided.","example":"MacBook Pro 14\" M3"},"serial_number":{"type":"string","description":"Serial number of the asset.","example":"C02ZX1ABCDEF"},"condition":{"type":"string","description":"Condition of the asset.","enum":["NEW","USED_LIKE_NEW","USED_GOOD","USED_FAIR","USED","USED_POOR","UNUSABLE"],"example":"NEW"},"renewal_date":{"type":"string","format":"date","description":"Renewal date for the asset. Defaults to a calculated date based on the organization's refresh policy if not provided.","example":"2027-01-15"},"person_id":{"type":"string","format":"uuid","description":"Person ID to assign the asset to. Mutually exclusive with office_id.","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"office_id":{"type":"string","format":"uuid","description":"Office ID to assign the asset to. Mutually exclusive with person_slug.","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"}},"required":["condition"]},"HookAccess":{"type":"object","properties":{"claims":{"$ref":"#/components/schemas/HookAccessClaims"}}},"HookAccessClaims":{"type":"object","properties":{"cid":{"type":"string"},"client_id":{"type":"string"}}},"HookAuthentication":{"type":"object","properties":{"protocol":{"type":"string"}}},"HookContext":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/HookRequest"},"protocol":{"$ref":"#/components/schemas/HookContextOauthProtocol"}}},"HookContextOauthProtocol":{"type":"object","properties":{"client":{"$ref":"#/components/schemas/HookOauthClient"},"request":{"$ref":"#/components/schemas/HookOauthProtocolRequest"}}},"HookCredential":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/HookUser"}}},"HookData":{"type":"object","properties":{"context":{"$ref":"#/components/schemas/HookContext"},"user":{"$ref":"#/components/schemas/HookUser"},"authentication":{"$ref":"#/components/schemas/HookAuthentication"},"session":{"$ref":"#/components/schemas/HookSession"},"identity":{"$ref":"#/components/schemas/HookIdentity"},"access":{"$ref":"#/components/schemas/HookAccess"}}},"HookIdentity":{"type":"object","properties":{"claims":{"$ref":"#/components/schemas/HookIdentityClaims"}}},"HookIdentityClaims":{"type":"object","properties":{"personId":{"type":"string"},"organization":{"type":"string"},"uid":{"type":"string"},"cid":{"type":"string"},"sub":{"type":"string"},"email":{"type":"string"}}},"HookOauthClient":{"type":"object","properties":{"id":{"type":"string"}}},"HookOauthProtocolRequest":{"type":"object","properties":{"client_id":{"type":"string"}}},"HookObject":{"type":"object","properties":{"type":{"type":"string"},"credential":{"$ref":"#/components/schemas/HookCredential"}}},"HookRequest":{"type":"object","properties":{"ipAddress":{"type":"string"},"userAgent":{"type":"string"}}},"HookSession":{"type":"object","properties":{"id":{"type":"string"}}},"HookUser":{"type":"object","properties":{"id":{"type":"string"},"profile":{"$ref":"#/components/schemas/HookUserProfile"}}},"HookUserProfile":{"type":"object","properties":{"email":{"type":"string"},"login":{"type":"string"}}},"OktaTokenHookRequest":{"type":"object","properties":{"source":{"type":"string"},"eventId":{"type":"string"},"eventTime":{"type":"string"},"eventType":{"type":"string"},"data":{"$ref":"#/components/schemas/HookData"},"object":{"$ref":"#/components/schemas/HookObject"}}},"HookCommand":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"array","items":{"$ref":"#/components/schemas/HookPatchOperation"}}},"required":["type","value"]},"HookPatchOperation":{"type":"object","properties":{"op":{"type":"string"},"path":{"type":"string"},"value":{}},"required":["op","path","value"]},"OktaTokenHookResponse":{"type":"object","properties":{"commands":{"type":"array","items":{"$ref":"#/components/schemas/HookCommand"}}},"required":["commands"]},"ShipmentNoticeInventoryResponseV1":{"type":"object","description":"Inventory associated with a shipment notice package item (V1)","properties":{"id":{"type":"string","format":"uuid","description":"Inventory ID","example":"123E4567-E89B-12D3-A456-426614174000"},"serialNumber":{"type":"string","description":"Serial number","example":"SN123456789"},"deployStatus":{"type":"string","description":"Deploy status","enum":["ARCHIVED","AVAILABLE","AWAITING_ARRIVAL","DEPLOYED","GIFTED","LOCKED","ON_HOLD","OUT_FOR_REPAIR","UNAVAILABLE","VOIDED"],"example":"AWAITING_ARRIVAL"},"warehouse":{"type":"null","$ref":"#/components/schemas/WarehouseRef","description":"Warehouse where the inventory is located"}},"required":["deployStatus","id"]},"ShipmentNoticeOrderItemResponse":{"type":"object","description":"Shipment notice order item","properties":{"id":{"type":"string","format":"uuid","description":"Item ID"},"sku":{"$ref":"#/components/schemas/SkuRef","description":"SKU reference"},"status":{"type":"string","description":"Item status","enum":["EXPECTED","PARTIALLY_EXPECTED","NO_LONGER_EXPECTED","RECEIVED","OVER_RECEIVED","PARTIALLY_RECEIVED","NOT_RECEIVED","CANCELLED"]},"quantity":{"type":"integer","format":"int32","description":"Quantity"},"description":{"type":"string","description":"Item description"},"createdAt":{"type":"string","format":"date-time","description":"Created timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last updated timestamp"}},"required":["createdAt","id","sku","status","updatedAt"]},"ShipmentNoticeOrderResponseV1":{"type":"object","description":"Shipment notice order (V1)","properties":{"id":{"type":"string","format":"uuid","description":"Shipment notice order ID"},"status":{"type":"string","description":"Order status","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","NOT_COMPLETED","CANCELLED"]},"sourceType":{"type":"string","description":"Source type","enum":["SUPPLIER","OFFICE"]},"condition":{"type":"string","description":"Condition of items","enum":["NEW","USED"]},"purchaseOrderNumber":{"type":"string","description":"Purchase order number"},"expectedShipDate":{"type":"string","format":"date","description":"Expected ship date"},"createdAt":{"type":"string","format":"date-time","description":"Created timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last updated timestamp"},"warehouse":{"$ref":"#/components/schemas/WarehouseRef","description":"Destination warehouse"},"shipmentNoticeOrderItems":{"type":"array","description":"Order line items","items":{"$ref":"#/components/schemas/ShipmentNoticeOrderItemResponse"}},"shipmentNoticePackages":{"type":"array","description":"Packages in this shipment notice","items":{"$ref":"#/components/schemas/ShipmentNoticePackageResponseV1"}},"submittedBy":{"type":"null","$ref":"#/components/schemas/PublicApiPersonRef","description":"Person who submitted the shipment notice."}},"required":["createdAt","id","shipmentNoticeOrderItems","shipmentNoticePackages","sourceType","status","updatedAt","warehouse"]},"ShipmentNoticePackageItemResponseV1":{"type":"object","description":"Shipment notice package item (V1)","properties":{"id":{"type":"string","format":"uuid","description":"Package item ID"},"status":{"type":"string","description":"Package item status","enum":["EXPECTED","RECEIVED","PARTIALLY_RECEIVED","OVER_RECEIVED","NOT_RECEIVED","CANCELLED"]},"expectedQuantity":{"type":"integer","format":"int32","description":"Expected quantity"},"receivedQuantity":{"type":"integer","format":"int32","description":"Received quantity"},"createdAt":{"type":"string","format":"date-time","description":"Created timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last updated timestamp"},"skuId":{"type":"string","format":"uuid","description":"SKU ID for this package item"},"vendorSku":{"type":"string","description":"Vendor SKU code"},"inventories":{"type":"array","description":"Inventories associated with this package item, ordered by createdAt asc","items":{"$ref":"#/components/schemas/ShipmentNoticeInventoryResponseV1"}}},"required":["createdAt","id","inventories","updatedAt"]},"ShipmentNoticePackageResponseV1":{"type":"object","description":"Shipment notice package (V1)","properties":{"id":{"type":"string","format":"uuid","description":"Package ID"},"status":{"type":"string","description":"Package status","enum":["PENDING","IN_TRANSIT","OUT_FOR_DELIVERY","ARRIVED_AT_PROCESSING_FACILITY","PARTIALLY_RECEIVED","FULLY_RECEIVED","OVER_RECEIVED","NOT_RECEIVED","CANCELLED","DELIVERY_EXCEPTION"]},"trackingCode":{"type":"string","description":"Tracking code"},"shippingCarrier":{"type":"string","description":"Shipping carrier"},"trackingUrl":{"type":"string","description":"Tracking URL"},"createdAt":{"type":"string","format":"date-time","description":"Created timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last updated timestamp"},"shipmentNoticePackageItems":{"type":"array","description":"Package items","items":{"$ref":"#/components/schemas/ShipmentNoticePackageItemResponseV1"}}},"required":["createdAt","id","shipmentNoticePackageItems","updatedAt"]},"SkuRef":{"type":"object","description":"SKU reference","properties":{"id":{"type":"string","format":"uuid","description":"SKU ID"},"vendorSku":{"type":"string","description":"Vendor SKU code"},"vendorCode":{"type":"string","description":"Vendor code"},"categoryCode":{"type":"string","description":"Category code"},"productTitle":{"type":"string","description":"Product title"}},"required":["id"]},"WarehouseRef":{"type":"object","description":"Warehouse reference","properties":{"id":{"type":"string","format":"uuid","description":"Warehouse ID"},"name":{"type":"string","description":"Warehouse name"}},"required":["id"]},"PatchShipmentNoticeItemRequest":{"type":"object","description":"Per-item update instruction inside a shipment.","properties":{"id":{"type":["string","null"],"format":"uuid","description":"Existing item ID. Required for update or delete; omit for additions."},"delete":{"type":"boolean","description":"When true, remove this item. Mutually exclusive with all other fields except `id`."},"skuId":{"type":"string","format":"uuid","description":"SKU ID for this item."},"quantity":{"type":"integer","format":"int32","description":"Expected quantity. Maps to domain expectedQuantity."},"regionId":{"type":"string","format":"uuid","description":"Region ID. Required when the org has MULTI_ENTITY_M1 enabled and regional transfer is disallowed. Enforcement of regional-transfer rules is handled by the domain layer (post-reconcile); violations are returned as a 400 with source 'shipmentNotice' rather than a field-level path."}},"required":["delete","quantity","regionId","skuId"]},"PatchShipmentNoticeRequest":{"type":"object","description":"Request body for partially updating a shipment notice. Omit a field to leave it unchanged. Explicit JSON null is rejected unless noted on each field. Editability follows the rules at /api/v1/shipment-notices/{id} GET response status fields: a shipment notice is editable when status is SUBMITTED or when status is PROCESSING and at least one shipment is PENDING.","properties":{"warehouseId":{"type":"string","format":"uuid","description":"New warehouse ID for the shipment notice. Only editable when the shipment notice is editable."},"condition":{"type":"string","description":"New condition. Only editable when shipment notice sourceType is OFFICE; rejected for any other source type.","enum":["NEW","USED"]},"purchaseOrderNumber":{"type":"string","description":"New purchase order number."},"shipmentNoticePackages":{"type":"array","description":"Per-package instructions. Omit to leave packages unchanged. Send `{id, delete: true}` to remove a package. Send `{...without id...}` to add a new package (only allowed when the shipment notice itself is editable). Send `{id, ...fields...}` to update a package (only allowed when that package is editable).","items":{"$ref":"#/components/schemas/PatchShipmentNoticeShipmentRequest"}}},"required":["condition","purchaseOrderNumber","shipmentNoticePackages","warehouseId"]},"PatchShipmentNoticeShipmentRequest":{"type":"object","description":"Per-shipment update instruction. See parent description.","properties":{"id":{"type":["string","null"],"format":"uuid","description":"Existing shipment ID. Required for update or delete; omit for additions."},"delete":{"type":"boolean","description":"When true, remove this shipment. Mutually exclusive with all other fields except `id`."},"shippingCarrier":{"type":"string","description":"Shipping carrier. Required together with trackingCode when either is present. Both are required when adding a shipment (omit id)."},"trackingCode":{"type":"string","description":"Tracking code. Required together with shippingCarrier when either is present. Both are required when adding a shipment (omit id). tracking_url is server-derived."},"items":{"type":"array","description":"Per-item instructions inside this package. Same add/update/delete semantics as `shipmentNoticePackages[]`.","items":{"$ref":"#/components/schemas/PatchShipmentNoticeItemRequest"}}},"required":["delete","items","shippingCarrier","trackingCode"]},"PublicAPIPatchReturnOrderItemsResponse":{"type":"object","description":"Returned after return-order items were processed successfully.","properties":{"returnOrderId":{"type":"string","format":"uuid","description":"Return order ID from the request path."},"updatedItemCount":{"type":"integer","format":"int32","description":"Number of items actually updated by the domain service."},"items":{"type":"array","description":"All return order items for this return order after the patch (same shape as GET return retrievals[].items).","items":{"$ref":"#/components/schemas/ReturnOrderItemInfo"}}},"required":["items","returnOrderId","updatedItemCount"]},"PublicAPIPatchReturnOrderItem":{"type":"object","description":"Update payload for a single return order item (org-app Process Return flow). When `status` is NOT_RETURNED, send `notReturnedDisposition`: DEPLOYED (keep inventory deployed, no deploy fields) or ARCHIVE (requires `deployReason`; non-blank `deployReasonDetails` when deployReason is OTHER). When `status` is RETURNED, omit disposition and deploy fields. Offboarding returns: domain validation may still require deployReason for NOT_RETURNED regardless of disposition.","properties":{"id":{"type":"string","format":"uuid","description":"Return order item ID."},"status":{"type":"string","description":"New status for the item.","enum":["RETURNED","NOT_RETURNED"]},"notReturnedDisposition":{"type":"string","description":"When status is NOT_RETURNED: DEPLOYED = keep deployed (omit deployReason); ARCHIVE = archive inventory (deployReason required). Omit when status is RETURNED.","enum":["DEPLOYED","ARCHIVE"]},"deployReason":{"type":"string","description":"Required when notReturnedDisposition is ARCHIVE. Omit when DEPLOYED.","enum":["ASSIGNED_TO_ADMIN","AWAITING_INFORMATION","BOUGHT_OUT","CANCELLED_BY_FIRSTBASE","CANCELLED_BY_VENDOR","CHURNED_CUSTOMER","DATA_ERROR","DATA_HOLD","DECOMMISSIONED_BY_EMPLOYER","DECOMMISSIONED_BY_FIRSTBASE","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","NEVER_RETURNED_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"]},"deployReasonDetails":{"type":"string","description":"When deployReason is OTHER, required non-blank text. Maximum length: 45 characters.","maxLength":45,"minLength":0}},"required":["id","status"]},"PublicAPIPatchReturnOrderItemsRequest":{"type":"object","description":"Bulk update payload for return order items (Process Return).","properties":{"items":{"type":"array","description":"One or more item updates. All items must belong to the path return order.","items":{"$ref":"#/components/schemas/PublicAPIPatchReturnOrderItem"},"minItems":1}},"required":["items"]},"GetPackageResponse":{"type":"object","description":"Package details returned by get/list package endpoints","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the package"},"name":{"type":"string","description":"Display name of the package"},"automaticOrder":{"type":"boolean","description":"When true, assigning this package can trigger automatic equipment ordering"},"approvalRequired":{"type":"boolean","description":"When true, orders from this package require admin approval"},"requireJustification":{"type":"boolean","description":"When true, requesters must provide a justification when ordering"},"slug":{"type":"string","description":"URL-safe unique identifier for the package"},"active":{"type":"boolean","description":"Whether the package is active"},"skuIds":{"type":"array","description":"SKU UUIDs included in this package","items":{"type":"string","format":"uuid"}},"assignedTo":{"$ref":"#/components/schemas/PackageAssignedToResponse","description":"People currently assigned to this package"},"notes":{"type":"array","description":"Notes associated with the package","items":{"$ref":"#/components/schemas/PackageNoteResponse"}}},"required":["active","approvalRequired","automaticOrder","id","name","notes","requireJustification","slug"]},"PackageAssignedToResponse":{"type":"object","description":"People assigned to a package","properties":{"people":{"type":"array","description":"Person UUIDs assigned to this package","items":{"type":"string","format":"uuid"}}}},"PackageNoteResponse":{"type":"object","description":"Package note details","properties":{"id":{"type":"string","format":"uuid","description":"Package note unique identifier","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},"note":{"type":"string","description":"Note text","example":"Remember to include the welcome letter"},"active":{"type":"boolean","description":"Whether the note is active","example":true}},"required":["id"]},"PublicAPIPatchPackageNoteRequest":{"type":"object","description":"Partial update payload for a package note (FBS-3321)","properties":{"note":{"type":"string","description":"Package note text"},"active":{"type":"boolean","description":"Set to false to deactivate the note. Must be a boolean if present; null is invalid."}},"required":["active","note"]},"PublicAPIPatchPackageRequest":{"type":"object","description":"Partial update payload for a package (FBS-3321)","properties":{"name":{"type":"string","description":"Package name"},"active":{"type":"boolean","description":"Set to false to soft-delete the package. Must be a boolean if present; null is invalid."},"approvalRequired":{"type":"boolean","description":"Whether package orders require approval"},"requireJustification":{"type":"boolean","description":"Whether order items in this package require justification"},"automaticOrder":{"type":"boolean","description":"Whether orders for this package are placed automatically"},"defaultOfficeId":{"type":"string","format":"uuid","description":"Default office UUID for OFFICE/FLEXIBLE delivery; cleared on PERSON delivery"},"deliverySetting":{"type":"string","description":"Package delivery setting (PERSON, OFFICE, FLEXIBLE)","enum":["PERSON","OFFICE","FLEXIBLE"]},"skus":{"type":"array","description":"SKU changes for the package. `null` (omitted) means no change. When present, each entry adds (`id` only) or removes (`id` + `delete: true`) a SKU. Existing SKUs not mentioned are unchanged. At least one entry is required when present.","items":{"$ref":"#/components/schemas/PublicAPIPatchPackageSkuRequest"}},"rules":{"type":"array","description":"Package rules. `null` (omitted) means no change. A present list replaces the package's rules (upsert/additive semantics, REQ-025).","items":{"$ref":"#/components/schemas/PublicAPIPatchPackageRuleRequest"}},"skuLines":{"type":"array","description":"Per-SKU region lines. `null` (omitted) means no change. A present list replaces stored SKU line regions.","items":{"$ref":"#/components/schemas/PackageSkuLineRequest"}},"usedEquipmentPreferences":{"type":"array","description":"Used-equipment preferences. `null` (omitted) means no change. A present list replaces the package's preferences (upsert/additive semantics, REQ-025).","items":{"$ref":"#/components/schemas/PublicAPIPatchUsedEquipmentPrefRequest"}}},"required":["active","approvalRequired","automaticOrder","defaultOfficeId","deliverySetting","name","requireJustification"]},"PublicAPIPatchPackageRuleRequest":{"type":"object","description":"Package rule entry for PATCH (mirrors UpdatePackageRuleDTO field names)","properties":{"categoryCode":{"type":"string","description":"Category code (e.g. LAPTOP)"},"optional":{"type":"boolean","description":"Whether the rule is optional"},"quantity":{"type":"integer","format":"int32","description":"Quantity for the rule"}},"required":["categoryCode","optional","quantity"]},"PublicAPIPatchPackageSkuRequest":{"type":"object","description":"SKU change for package PATCH","properties":{"id":{"type":"string","format":"uuid","description":"SKU UUID (catalog id)"},"delete":{"type":["boolean","null"],"description":"When true, delete/unlink this SKU from the package. Defaults to false. The legacy key `remove` is accepted as a deprecated alias for `delete`."}},"required":["id"]},"PublicAPIPatchUsedEquipmentPrefRequest":{"type":"object","description":"Used-equipment preference entry for PATCH","properties":{"categoryCode":{"type":"string","description":"Category code identifying which preference to update (e.g. LAPTOP)","minLength":1},"preference":{"type":"string","description":"Used-equipment preference value","enum":["NEW_FIRST","NEW_ONLY","USED_FIRST","USED_ONLY"]}},"required":["categoryCode","preference"]},"PublicAPIPatchOrderItem":{"type":"object","description":"Line in `products`. Same shape as create-order `skus[]` for condition: only `preferredCondition` (NEW or USED); used-equipment preference is derived as on create (NEW→NEW_ONLY, USED→USED_ONLY, omitted→NEW_ONLY). Omit `id` for a newly added row. Include `id` to update expedited shipping or preferred condition, or set `cancelled: true` to cancel that line. Omitted existing lines are not cancelled.","properties":{"id":{"type":["string","null"],"format":"uuid","description":"Existing order item id when updating that line's expedited shipping or preferred condition."},"cancelled":{"type":["boolean","null"],"description":"If true, cancel this line. Requires `id`. Defaults to false."},"vendorSku":{"type":["string","null"],"description":"Vendor SKU when adding a new line (required together with vendorCode)."},"vendorCode":{"type":["string","null"],"description":"Vendor code when adding a new line (required together with vendorSku)."},"expeditedShippingOption":{"type":["string","null"],"description":"Expedited shipping for this line. Allowed: EXPEDITED_STANDARD. Explicit null clears.","enum":["EXPEDITED_STANDARD"]},"preferredCondition":{"type":["string","null"],"description":"Physical condition for this line. Allowed values: NEW, USED.","enum":["NEW","USED"]},"justification":{"type":["string","null"],"description":"Order-item justification text. Omit to leave unchanged; explicit null is treated as unchanged."},"intendedFulfillmentMethod":{"type":["string","null"],"description":"Create/modify-time fulfillment intent (WAREHOUSE or DROPSHIP). Distinct from fulfill-time fulfillmentMethod on GET. Omit to leave unchanged / legacy. Honored when feature flag fbs-4375-one-off-fulfillment-source is on. For DROPSHIP the server resolves catalog pricing, warranty pricing, and discount for the order shipping region — clients must not send pricingId, warrantyPricingId, or discountedPrice. WAREHOUSE clears sticky money via shared sync. Procurement (DROPSHIP) is not expeditable.","enum":["WAREHOUSE","DROPSHIP"]}},"required":["expeditedShippingOption","intendedFulfillmentMethod","justification","preferredCondition","vendorCode","vendorSku"]},"PublicAPIPatchOrderRequest":{"type":"object","description":"Request body for modifying or cancelling an existing order. All fields are optional — omit any field to leave it unchanged. To cancel the entire order, send only `{\"status\": \"CANCELLED\"}` (valid when order items are ORDERED, AWAITING_APPROVAL, or DECLINED). Explicit JSON null is honored only where noted on each field; other explicit nulls are ignored or rejected. Deliver-to person/office IDs do not support clear via explicit null—omit those keys to leave deliver-to unchanged.","properties":{"products":{"type":"array","description":"When present, declares how order lines should look after this update (must contain at least one item). Lines that include `id` are kept for in-place edits (expedited / preferred condition) unless `cancelled` is true. Lines without `id` are treated as additions. Existing lines whose `id` is omitted from this array are left unchanged. To cancel a line, include its `id` with `cancelled: true`. Cancelled rows remain in storage and in GET/PATCH responses.","items":{"$ref":"#/components/schemas/PublicAPIPatchOrderItem"}},"shippingAddress":{"$ref":"#/components/schemas/PublicAPIUpdateShippingAddress","description":"New shipping address (full replace)."},"deliverToPersonId":{"type":"string","format":"uuid","description":"Deliver-to person ID. Mutually exclusive with deliverToOfficeId when both are non-null. Omit to leave unchanged; explicit null is accepted but does not clear an existing deliver-to target."},"deliverToOfficeId":{"type":"string","format":"uuid","description":"Deliver-to office ID. Mutually exclusive with deliverToPersonId when both are non-null. Omit to leave unchanged; explicit null is accepted but does not clear an existing deliver-to target."},"status":{"type":["string","null"],"description":"Set to CANCELLED to cancel the entire order. Only CANCELLED is accepted. Omit the field to leave status unchanged; explicit null is invalid.","enum":["CANCELLED"]}},"required":["deliverToOfficeId","deliverToPersonId","products","shippingAddress","status"]},"PublicAPIUpdateShippingAddress":{"type":"object","description":"Shipping address for an order modification request","properties":{"addressLine1":{"type":["string","null"],"description":"The primary line of the address (e.g., house number and street name)","example":"123 Main Street"},"addressLine2":{"type":["string","null"],"description":"Additional address information (e.g., apartment or suite number)","example":"Apartment B"},"administrativeArea":{"type":["string","null"],"description":"The state, province, or region within the country","example":"California"},"countryCode":{"type":"string","description":"A two-letter ISO 3166-1 alpha-2 code representing the country","example":"US"},"dependentLocality":{"type":["string","null"],"description":"A smaller subdivision within the locality, often used for neighborhoods or districts","example":"Mission Bay"},"locality":{"type":["string","null"],"description":"The city or town within the administrative area","example":"San Francisco"},"postalCode":{"type":["string","null"],"description":"The ZIP code or equivalent postal code","example":"94158"},"sortingCode":{"type":["string","null"],"description":"A code used for routing or sorting mail, often specific to postal systems.","example":"94158-1234"},"phoneNumber":{"type":["string","null"],"description":"A contact phone number, including the international dialing code","example":"+1-415-555-1234"}},"required":["countryCode"]},"AddressResponse":{"type":"object","description":"Office address","properties":{"street1":{"type":"string","description":"Street address line 1","example":"123 Main Street"},"street2":{"type":"string","description":"Street address line 2","example":"Suite 100"},"city":{"type":"string","description":"City","example":"San Francisco"},"province":{"type":"string","description":"State or province","example":"California"},"postalCode":{"type":"string","description":"Postal / ZIP code","example":"94105"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"US"},"phoneNumber":{"type":"string","description":"Contact phone number for the office","example":"+15551234567"}}},"OfficeResponse":{"type":"object","description":"An office location belonging to the organization","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this office","example":"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"},"name":{"type":"string","description":"Display name of the office","example":"HQ Office"},"contactName":{"type":"string","description":"Name of the contact person at this office, used for shipping and logistics","example":"Jane Doe"},"address":{"$ref":"#/components/schemas/AddressResponse","description":"Physical address of this office, used for equipment deliveries and returns"},"active":{"type":"boolean","description":"Whether this office is currently active. Inactive offices cannot receive new orders or returns","example":true}},"required":["active","address","id","name"]},"PublicAPIOfficeAddress":{"type":"object","description":"Office address (full replace)","properties":{"street1":{"type":"string","description":"Street address line 1","example":"123 Main Street","maxLength":255,"minLength":0},"street2":{"type":"string","description":"Street address line 2","example":"Suite 100","maxLength":255,"minLength":0},"city":{"type":"string","description":"City","example":"San Francisco","maxLength":255,"minLength":0},"province":{"type":"string","description":"State or province","example":"California","maxLength":255,"minLength":0},"postalCode":{"type":"string","description":"Postal / ZIP code","example":"94105","maxLength":32,"minLength":0},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"US","maxLength":2,"minLength":2},"phoneNumber":{"type":"string","description":"Contact phone number for the office","example":"+15551234567","maxLength":32,"minLength":0},"postalCodeField":{"type":"string"},"countryCodeField":{"type":"string"},"phoneNumberField":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"administrativeArea":{"type":"string"},"dependentLocality":{"type":"string"},"locality":{"type":"string"},"sortingCode":{"type":"string"},"integrations":{"$ref":"#/components/schemas/UpdateAddressIntegrations"},"validate":{"type":"boolean"}},"required":["addressLine1","city","countryCode","countryCodeField","integrations","locality","street1"]},"PublicAPIPatchOfficeRequest":{"type":"object","description":"Partial update payload for an office (FBS-3322)","properties":{"name":{"type":"string","description":"Office name"},"contactName":{"type":"string","description":"Office contact name"},"address":{"$ref":"#/components/schemas/UpdateAddress","description":"Office address (full replace when present)"},"active":{"type":"boolean","description":"Set to false to soft-delete the office. Must be a boolean if present; null is invalid. Reactivation (true) is not supported.","example":false},"nameField":{"type":"string"},"contactNameField":{"type":"string"},"addressField":{"$ref":"#/components/schemas/PublicAPIOfficeAddress"},"activeField":{"type":"boolean"}},"required":["active","activeField","address","addressField","contactName","contactNameField","name","nameField"]},"UpdateAddress":{"type":"object","properties":{"countryCode":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"administrativeArea":{"type":"string"},"dependentLocality":{"type":"string"},"locality":{"type":"string"},"postalCode":{"type":"string"},"sortingCode":{"type":"string"},"phoneNumber":{"type":"string"},"integrations":{"$ref":"#/components/schemas/UpdateAddressIntegrations"},"validate":{"type":"boolean"}}},"UpdateAddressIntegrations":{"type":"object","properties":{"provider":{"type":"string","enum":["MERGE","WEBHOOK","JUMPCLOUD","JAMF","KANDJI","INTUNE","SAILPOINT"]},"integrationAddressId":{"type":"string"},"mergeTenant":{"type":"string","enum":["US","EU"]}}},"AppleBusiness":{"type":"object","description":"Apple Business Manager assignment status for a serialized Apple inventory item","properties":{"assignmentStatus":{"type":"string","description":"Whether the device is assigned in Apple Business Manager","enum":["ASSIGNED","NOT_ASSIGNED"],"example":"ASSIGNED"},"lastSyncTimestamp":{"type":["string","null"],"format":"date-time","description":"UTC timestamp of the last successful ABM sync for this device; null when never synced","example":"2026-07-01T12:00:00Z"},"nextSyncTimestamp":{"type":"string","format":"date-time","description":"UTC timestamp of the next scheduled ABM full sync","example":"2026-07-02T02:00:00Z"}},"required":["assignmentStatus","nextSyncTimestamp"]},"InboundRetrievalInfo":{"allOf":[{"$ref":"#/components/schemas/RetrievalMethodInfo"},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this retrieval method record"},"status":{"type":"string","description":"Current status of the inbound label retrieval process","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"]},"inboundTrackingCode":{"type":"string","description":"Tracking code for the inbound return shipment","example":"1Z999AA10123456784"},"inboundTrackingLink":{"type":"string","description":"URL to track the inbound return shipment"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when this retrieval record was last updated"}}}],"description":"Inbound label retrieval: a pre-paid shipping label is sent to the employee to pack and ship the equipment","required":["id"]},"Inventory":{"type":"object","description":"A single inventory item (piece of equipment) belonging to the organization","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this inventory item","example":"ecb7e933-de1e-9830-b180-b25d1d0d296e"},"skuId":{"type":"string","format":"uuid","description":"The SKU (product variant) ID this inventory item is associated with","example":"203a5df2-423a-43a9-bb19-1ccaf3434b91"},"serialNumber":{"type":"string","description":"Hardware serial number of the device; null for non-serialized items","example":"25f2e6ea9a"},"imei":{"type":"array","description":"IMEI(s) for cellular devices. GSMA-allocated 14- or 15-digit numeric strings. Empty array when not applicable.","items":{"type":"string","example":"356789012345678"}},"deployStatus":{"type":"string","description":"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.","enum":["ARCHIVED","AVAILABLE","AWAITING_ARRIVAL","DEPLOYED","ON_HOLD","UNAVAILABLE"],"example":"ARCHIVED"},"deployReason":{"type":"string","description":"Reason code explaining why the item is in its current deployStatus. Required when transitioning to UNAVAILABLE or ARCHIVED; null when DEPLOYED or AVAILABLE.","enum":["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"],"example":"LOST_BY_WORKER"},"condition":{"type":"string","description":"Physical condition of the item (NEW or USED)","enum":["NEW","USED_LIKE_NEW","USED_GOOD","USED_FAIR","USED","USED_POOR","UNUSABLE"],"example":"NEW"},"categoryCode":{"type":"string","description":"Category code of the SKU (e.g. COMPUTER, MONITOR, HEADSET)","example":"TSHIRT"},"categoryNameOfSku":{"type":"string","description":"Human-readable category name for the SKU","example":"T-shirt"},"skuTitle":{"type":"string","description":"Display title of the SKU (product variant name)","example":"T-shirt White - 5XL"},"vendorCode":{"type":"string","description":"Vendor/brand code for the SKU","example":"AWESOME_MERCHANDISE"},"vendorSku":{"type":"string","description":"Vendor-specific SKU or model identifier","example":"TSHRT_5XL_WHITE"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when this inventory item was created in Firstbase","example":"2023-02-09T00:00:00"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when this inventory item was last updated","example":"2023-03-02T17:39:01.650027"},"renewalDate":{"type":"string","format":"date","description":"Date when this item is scheduled for renewal or replacement","example":"2026-02-09"},"renewalDateUpdatedBy":{"type":"string","description":"Who or what last set the renewalDate (e.g. organization policy vs. manual override)","enum":["RENEWAL_DATE_ORGANIZATION_LEVEL","RENEWAL_DATE_ORGANIZATION_CATEGORY_LEVEL","RENEWAL_DATE_MANUALLY_UPDATED","CLEAR_RENEWAL_DATE_MANUALLY_SET"],"example":"RENEWAL_DATE_ORGANIZATION_LEVEL"},"billingStartDate":{"type":"string","format":"date","description":"Date when billing began for this inventory item","example":"2026-02-09"},"billingEndDate":{"type":"string","format":"date","description":"Date when billing ended or is scheduled to end for this inventory item","example":"2028-02-09"},"procurementMethod":{"type":"string","description":"Human-readable label indicating how this item was procured (e.g. via an inventory order ID)","example":"Inventory Order - #c853d81c-ba0b-4027-a394-d5586b61608c"},"returnOrder":{"type":"null","$ref":"#/components/schemas/InventoryReturnInfo","description":"Details of the return order associated with this inventory item, if a return has been initiated."},"assignedTo":{"type":"null","$ref":"#/components/schemas/InventoryAssignedToInfo","description":"Information about the person this inventory item is currently assigned to, if applicable."},"tags":{"type":"array","description":"List of key-value tags attached to this inventory item for organization and filtering.","items":{"$ref":"#/components/schemas/InventoryTag"},"uniqueItems":true},"pricing":{"$ref":"#/components/schemas/SimplifiedProductPriceDTO","description":"Pricing details"},"description":{"type":"string","description":"Custom description for the inventory item","example":"Custom inventory description"},"netsuiteInvoiceId":{"type":"string","description":"NetSuite invoice ID for Firstbase-supplied inventory","example":"INV-123456"},"holdStartDate":{"type":["string","null"],"format":"date","description":"Date when the machine retention hold started (set at warehouse receive). Null when no hold is active."},"unlockDate":{"type":["string","null"],"format":"date","description":"Date when the machine retention hold expires (holdStartDate + holdPeriodDays). Null when no hold is active."},"itadRequested":{"type":["boolean","null"],"description":"Whether ITAD was requested for this item. Copied from the return order item at hold-stamp time."},"appleBusiness":{"type":"null","$ref":"#/components/schemas/AppleBusiness","description":"Apple Business Manager assignment for serialized Apple inventory. Omitted for non-Apple or non-serialized items."},"assignedCountryCode":{"type":["string","null"],"description":"Assigned country/region code (inventory region code, same as Client App Assigned country). Present, including JSON null when unset, only when the organization does not allow regional transfer. Omitted when regional transfer is allowed.","example":"DE"}},"required":["assignedCountryCode","categoryCode","categoryNameOfSku","condition","createdAt","deployStatus","id","imei","skuId","skuTitle","tags","updatedAt","vendorCode","vendorSku"]},"InventoryAssignedToInfo":{"type":"object","description":"Details about who or what the inventory item is currently assigned to","properties":{"id":{"type":"string","format":"uuid","description":"ID of the person, office, or warehouse this item is assigned to","example":"371da231-5878-45b1-80a3-9113f8795c29"},"type":{"type":"string","description":"Type of the assignee: PERSON, OFFICE, or WAREHOUSE","enum":["PERSON","WAREHOUSE","OFFICE"],"example":"PERSON"},"label":{"type":"string","description":"Human-readable identifier for the assignee — email address for a person, name for an office or warehouse","example":"jane@example.com"},"assignedAt":{"type":"string","format":"date-time","description":"Timestamp when this item was assigned to the current assignee; null when the assignment date is unknown"}},"required":["id","label","type"]},"InventoryReturnInfo":{"type":"object","description":"Return order information associated with this inventory item; null when the item has no active return order","properties":{"id":{"type":"string","format":"uuid","description":"Return order ID","example":"371da231-5878-45b1-80a3-9113f8795c29"},"status":{"type":"string","description":"Overall status of the return order","enum":["PENDING","PROCESSING","COMPLETED","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED"]},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the return order was created"},"returnOrderItemId":{"type":"string","format":"uuid","description":"ID of the individual return order item for this inventory piece","example":"371da231-5878-45b1-80a3-9113f8795c29"},"returnOrderItemStatus":{"type":"string","description":"Status of this specific item within the return order","enum":["PENDING","PROCESSING","COMPLETED","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","SUBMITTED","CANCELLED","NONE","CONFIRMED","PARTIALLY_COMPLETED","NOT_COMPLETED"]},"retrievalMethod":{"description":"How the item is being retrieved (e.g. return kit, prepaid label, or in-person drop-off)","oneOf":[{"$ref":"#/components/schemas/InboundRetrievalInfo"},{"$ref":"#/components/schemas/PhysicalRetrievalInfo"},{"$ref":"#/components/schemas/ReturnKitRetrievalInfo"}]}}},"PhysicalRetrievalInfo":{"allOf":[{"$ref":"#/components/schemas/RetrievalMethodInfo"},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this retrieval method record"},"status":{"type":"string","description":"Current status of the physical retrieval process","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"]},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when this retrieval record was last updated"}}}],"description":"Physical retrieval: the equipment is dropped off in person or collected by a courier at the employee's location","required":["id"]},"RetrievalMethodInfo":{"description":"The method used to retrieve (collect) the equipment for a return order. The `type` discriminator indicates which concrete type this is: RETURN_KIT, INBOUND_LABEL, or PHYSICAL.","discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string"}},"required":["type"]},"ReturnKitRetrievalInfo":{"allOf":[{"$ref":"#/components/schemas/RetrievalMethodInfo"},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this retrieval method record"},"status":{"type":"string","description":"Current status of the return kit retrieval process","enum":["REQUESTED","PROCESSED","CANCELLED","LABEL_CREATED","SHIPPED","DELIVERED","SENT_BACK","ARRIVED_AT_PROCESSING_FACILITY","DELIVERY_EXCEPTION","NOT_PROCESSED","PARTIALLY_PROCESSED","SCHEDULING_PICK_UP"]},"inboundTrackingCode":{"type":"string","description":"Tracking code for the inbound shipment (kit being sent to the employee)","example":"1Z999AA10123456784"},"inboundTrackingLink":{"type":"string","description":"URL to track the inbound kit shipment"},"outboundTrackingCode":{"type":"string","description":"Tracking code for the outbound return shipment (equipment coming back to the warehouse)","example":"1Z999AA10123456784"},"outboundTrackingLink":{"type":"string","description":"URL to track the outbound return shipment"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when this retrieval record was last updated"}}}],"description":"Return kit retrieval: Firstbase ships a pre-paid return kit to the employee who packs and ships the equipment back","required":["id"]},"SimplifiedProductPriceDTO":{"type":"object","properties":{"regionCode":{"type":"string"},"priceOption":{"type":"string"},"price":{"type":"number"},"currencyCode":{"type":"string"},"discountedPrice":{"type":"number"},"discountPercentage":{"type":"number"}},"required":["currencyCode","discountPercentage","discountedPrice","price","priceOption","regionCode"]},"Assignee":{"type":"object","description":"Update the assignment of the inventory","properties":{"id":{"type":"string","format":"uuid","description":"The ID of the person/office to assign the item to","example":"00000000-0000-0000-0000-000000000000"},"type":{"type":"string","description":"Type of assignee","enum":["PERSON","OFFICE"],"example":"OFFICE"}},"required":["id","type"]},"UpdateInventoryRequest":{"type":"object","description":"Request body for updating inventory details","properties":{"deployStatus":{"type":"string","description":" \n            Allowed values:\n            - `UNAVAILABLE`, only applies to inventory assigned to an office.\n            - `AVAILABLE`, only applies to inventory assigned to an office.\n            - `DEPLOYED`, only applies to inventory assigned to a person.\n            - `ARCHIVED`, applies to inventory assigned to a person or an office.\n        ","enum":["ARCHIVED","DEPLOYED","UNAVAILABLE","AVAILABLE"],"example":"ARCHIVED"},"deployReason":{"type":"string","description":"\n            Reason for the deployment change. \n            Allowed values vary based on `deployStatus`:\n            - 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].\n            - 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].\n            - For `AVAILABLE`, reason must be null.\n            - For `DEPLOYED`, reason must be null.\n        ","enum":["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"],"example":"GIFTED_BY_EMPLOYER"},"assignedTo":{"$ref":"#/components/schemas/Assignee"},"imei":{"type":["array","null"],"description":"Optional IMEI(s) for cellular/mobile inventory only. Omit this field when updating other attributes (for example renewalDate on laptops). Omit or send null to leave unchanged; send [] to clear all IMEIs. When provided, each value must be a 14- or 15-digit ASCII numeric string (GSMA IMEI).","items":{"type":"string","example":"356789012345678","pattern":"^\\d{14,15}$"}},"condition":{"type":"string","description":"Condition of the inventory item.","enum":["NEW","USED"],"example":"NEW"},"renewalDate":{"type":"string","format":"date","description":"Renewal date for the inventory item. Editable when inventory is customer-supplied OR Firstbase-purchased non-subscription.","example":"2027-01-15"},"serialNumber":{"type":"string","description":"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.","example":"SN-ABC-123"},"description":{"type":"string","description":"Free-text description. Editable only for generic SKUs (customer-supplied) AND assigned to person/office AND not in return progress.","example":"Refurbished MacBook Pro 14\""},"vendorCode":{"type":"string","description":"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.","example":"APPLE"},"vendorSku":{"type":"string","description":"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.","example":"MBP14-M3-512"}}},"PublicAPIPatchInventoryOrderItem":{"type":"object","description":"Inventory-order line patch entry. Three modes:\n  - Add: omit `id`. Require `skuId`, `pricingId`, `quantity`.\n  - Update: include `id` plus any subset of {quantity, discountedPrice, warrantyPricingId, inventoryOrderItemType}. Server prefills `skuId`, `pricingId`, `discountedPrice`, `warrantyPricingId`, and `inventoryOrderItemType` from the existing row when omitted.\n  - Delete: send `{\"id\": \"...\", \"delete\": true}`. All other fields ignored.","properties":{"id":{"type":["string","null"],"format":"uuid","description":"Existing line id. Omit to add a new line; include to update or delete."},"skuId":{"type":"string","format":"uuid","description":"SKU id. Required when adding."},"pricingId":{"type":"string","format":"uuid","description":"Pricing id. Required when adding."},"quantity":{"type":"integer","format":"int32","description":"Quantity (>= 1). Required when adding."},"discountedPrice":{"type":["number","null"],"description":"Discounted unit price. Optional; defaults to pricing's discount."},"warrantyPricingId":{"type":["string","null"],"format":"uuid","description":"Warranty pricing id, if applicable."},"inventoryOrderItemType":{"type":["string","null"],"description":"Item type. Defaults to PHYSICAL.","enum":["PHYSICAL","SERVICE"]},"delete":{"type":["boolean","null"],"description":"If true, cancel this line. Requires `id`."}},"required":["discountedPrice","inventoryOrderItemType","pricingId","quantity","skuId","warrantyPricingId"]},"PublicAPIPatchInventoryOrderRequest":{"type":"object","description":"Request body for modifying an inventory order. All five top-level fields are optional. Omit a field to leave it unchanged. Behaviour depends on the order's current status:\n\n  - SUBMITTED: all five fields are writable.\n  - PROCESSING or SHIPPED: only `customerPoNumber` may be present in the body. Sending any other field (even with a value equal to the current one) returns 409 Conflict.\n  - Any other status (ORDERED, RECEIVED, PARTIALLY_RECEIVED, COMPLETE, CANCELLED): the endpoint returns 409 Conflict.\n\nSending `{}` (no fields) returns 400 Bad Request.\nItems semantics: if `items` is omitted entirely, the existing lines are left unchanged. If `items` is sent as `[]`, the request is rejected (an order must have at least one active line). Per entry: omit `id` to add a new line; include `id` (with any subset of other fields) to update — server prefills skuId, pricingId, discountedPrice, warrantyPricingId, and type from the existing row. Send `{\"id\": \"...\", \"delete\": true}` to cancel a specific line. Existing lines whose id is not mentioned are left alone.","properties":{"warehouseId":{"type":"string","format":"uuid","description":"New warehouse for the order. Writable only when status is SUBMITTED."},"regionId":{"type":"string","format":"uuid","description":"New region. Writable only when status is SUBMITTED."},"customerPoNumber":{"type":["string","null"],"description":"Customer PO number. Writable when status is SUBMITTED, PROCESSING, or SHIPPED. Send an explicit JSON null to clear the existing value; omit the key to leave it unchanged."},"billingType":{"type":"string","description":"Billing type. Writable only when status is SUBMITTED.","enum":["SUBSCRIPTION","PURCHASED"]},"items":{"type":"array","description":"Optional list of item changes. Omit the key to leave items unchanged. Sending an empty array returns 409 (orders must keep at least one active line).","items":{"$ref":"#/components/schemas/PublicAPIPatchInventoryOrderItem"}}},"required":["billingType","customerPoNumber","regionId","warehouseId"]},"UpdateInventoryLevelRequest":{"type":"object","description":"\n        Partial update for an inventory level. Only the fields listed in this schema are accepted.\n\n        IMPORTANT: This endpoint does NOT accept skuId, warehouseId, or regionId — these are\n        immutable after creation. Sending any of them returns 400 with a per-field error\n        (Cannot change <field> after creation). Sending any other field name returns 400\n        with detail Unknown field: <name>. Sending an empty body returns 400 At least one\n        modifiable field must be provided. Fields skuId, warehouseId, and regionId are\n        not editable after the inventory level has been created.\n\n        Setting active to false soft-deletes the inventory level. Reactivating via PATCH\n        (active=true on an inactive level) is not supported; use POST /api/inventory-levels.\n        Sending active=true on an already-active level is a 200 no-op (no state change).\n\n        NOTE: Sending a wrong type for a numeric field (e.g. minQuantity: \"foo\") returns 400\n        with detail \"Field \\\"<field>\\\" is missing or has an invalid value\" — this is the global\n        deserialization error shape, not the per-field aggregated shape described above.\n    ","properties":{"minQuantity":{"type":"integer","format":"int32","description":"New minimum quantity threshold (>= 1).","example":5},"maxQuantity":{"type":"integer","format":"int32","description":"New maximum quantity threshold (>= 1; must be > minQuantity unless both equal 1).","example":20},"includeUsed":{"type":"boolean","description":"Whether to include used inventory in stock calculations.","example":false},"autoCreate":{"type":"boolean","description":"Whether to automatically create restock orders when stock is low.","example":false},"active":{"type":"boolean","description":"Set to false to soft-delete the inventory level. Setting true on an inactive level is rejected.","example":false},"customerPoNumber":{"type":"string","description":"Customer purchase order number to apply to restock orders created from this level","example":"PO-12345"},"unknownFields":{"type":"object","additionalProperties":{}}},"required":["unknownFields"]},"UsersSchema":{"type":"object","properties":{"totalResults":{"type":"integer","format":"int64","description":"The total number of users available","example":102},"itemsPerPage":{"type":"integer","format":"int32","description":"The number of users in the returned page","example":1},"startIndex":{"type":"integer","format":"int32","description":"The 1-based index of the first user in the returned page","example":1},"Resources":{"type":"array","description":"A page of users","items":{"$ref":"#/components/schemas/UserSchema"}},"schemas":{"type":"array","description":"The schemas defining the attributes of the user resources list.","example":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"items":{"type":"string"}}},"required":["Resources","itemsPerPage","schemas","startIndex","totalResults"]},"PageDTO":{"type":"object","description":"Standard paginated response wrapper used by all list endpoints. Use `pageNumber` and `size` to paginate; stop when `pageNumber >= totalPages`.","properties":{"size":{"type":"integer","format":"int32","description":"Maximum number of items per page as requested","example":10},"totalElements":{"type":"integer","format":"int64","description":"Total number of items matching the query across all pages","example":42},"totalPages":{"type":"integer","format":"int32","description":"Total number of pages based on totalElements / size","example":5},"pageNumber":{"type":"integer","format":"int32","description":"Current page number, 1-based (first page = 1)","example":1},"data":{"type":"array","description":"Items in the current page; may be fewer than `size` on the last page","items":{}}},"required":["data","pageNumber","size","totalElements","totalPages"]},"WarehouseResponseDto":{"type":"object","description":"A Firstbase warehouse location where inventory can be stocked and shipment notices directed","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this warehouse; use this ID when creating inventory orders or shipment notices","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},"name":{"type":"string","description":"Display name of the warehouse","example":"US East Warehouse"},"address":{"$ref":"#/components/schemas/AddressResponse","description":"Physical address of the warehouse; null when not yet configured"}},"required":["id","name"]},"PaginatedShipmentDetailsDto":{"type":"object","properties":{"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"},"pageNumber":{"type":"integer","format":"int32"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentOrderItemDto"}}},"required":["data","pageNumber","size","totalElements","totalPages"]},"ShipmentOrderItemDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Shipment ID","example":"123E4567-E89B-12D3-A456-426614174000"},"trackingCode":{"type":"string","description":"Tracking code","example":"1Z00000000"},"carrier":{"type":"string","description":"The carrier name","example":"UPS"},"status":{"type":"string","description":"The current status of the shipment","example":"DELIVERED"},"trackingHistory":{"type":"array","description":"A history of recorded shipment status updates in order of date received","items":{"$ref":"#/components/schemas/ShipmentStatusDTO"}},"createdAt":{"type":"string","format":"date-time","description":"Timestamp at which the record was created"},"orderItemIds":{"type":"array","description":"A list of associated Order item IDs","examples":["123E4567-E89B-12D3-A456-426614174000","123E4567-E89B-12D3-A456-426614175000"],"items":{"type":"string","format":"uuid"}},"trackingUrl":{"type":"string","description":"Tracking link","example":"http://trackinglink.com/trackingcode"}},"required":["carrier","createdAt","id","status","trackingCode","trackingHistory"]},"ShipmentStatusDTO":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal id of the tracker status","example":"123E4567-E89B-12D3-A456-426614174000"},"status":{"type":"string","description":"The status of the shipment","example":"IN_TRANSIT"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp at which the event was received"}},"required":["createdAt","id","status"]},"PublicAPIGetReplacementResponse":{"type":"object","description":"Replacement details","properties":{"id":{"type":"string","format":"uuid","description":"Replacement ID","example":"123E4567-E89B-12D3-A456-426614174000"},"status":{"type":"string","description":"Replacement status","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","CANCELLED"],"example":"SUBMITTED"},"createdAt":{"type":"string","format":"date","description":"Date the replacement was created","example":"2025-01-15"},"person":{"$ref":"#/components/schemas/PublicApiPersonRef","description":"Person associated with the replacement"},"submittedBy":{"$ref":"#/components/schemas/PublicApiPersonRef","description":"Person who submitted the replacement"},"order":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse","description":"Replacement order details"},"returnOrder":{"$ref":"#/components/schemas/PublicAPIGetOrderResponse","description":"Return order details"}},"required":["createdAt","id","status"]},"RegionResponseDto":{"type":"object","description":"A geographic region that scopes inventory levels and warehouse coverage for the organization","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this region; use this ID when creating inventory levels or inventory orders","example":"00000000-0000-0000-0000-000000000000"},"regionCode":{"type":"string","description":"Short code identifying the region (e.g. ISO country code or custom org-defined code)","example":"US"},"name":{"type":"string","description":"Human-readable name of the region","example":"United States"}},"required":["id","name","regionCode"]},"PublicAPINewJoinerStatsResponse":{"type":"object","description":"Aggregate counts for the new joiner dashboard status cards and provisioning outcomes","properties":{"totalUpcoming":{"type":"integer","format":"int32","description":"Total upcoming new joiners (active pipeline only)","example":42},"notStarted":{"type":"integer","format":"int32","description":"New joiners with no order placed yet","example":10},"orderPlaced":{"type":"integer","format":"int32","description":"New joiners with an order placed but not yet ready","example":15},"ready":{"type":"integer","format":"int32","description":"New joiners whose equipment is ready","example":12},"atRisk":{"type":"integer","format":"int32","description":"New joiners at risk (start date approaching, equipment not ready)","example":3},"late":{"type":"integer","format":"int32","description":"New joiners who are late (start date passed, equipment not ready)","example":2},"onTimeProvisioningCount":{"type":"integer","format":"int32","description":"Count of new joiners provisioned on time","example":38},"lateProvisioningCount":{"type":"integer","format":"int32","description":"Count of new joiners provisioned late","example":4}},"required":["atRisk","late","lateProvisioningCount","notStarted","onTimeProvisioningCount","orderPlaced","ready","totalUpcoming"]},"AssignedPackage":{"type":"object","description":"A package assigned to the new joiner.","properties":{"id":{"type":"string","format":"uuid","description":"Package ID"},"name":{"type":"string","description":"Package name","example":"Laptop"}},"required":["id","name"]},"OrderRef":{"type":"object","description":"Reference to the most recent equipment order for this new joiner. Null when the new joiner has not been ordered for yet. Fetch GET /api/orders/{id} for full order details.","properties":{"id":{"type":"string","format":"uuid","description":"Order ID"},"status":{"type":"string","description":"Order status","enum":["AWAITING_APPROVAL","ORDERED","PROCESSING","ORDERED_NOT_SHIPPED","SHIPPED","COMPLETED","PARTIALLY_SHIPPED","DECLINED","AWAITING_DELIVERY_SCHEDULING","DELIVERY_SCHEDULED","DELIVERED","ACTIVATED","NONE","APPROVED","AWAITING_FULFILLMENT","ACTION_REQUIRED","PENDING","RETURN_KIT_SENT","RETURN_KIT_DELIVERED","RETURN_KIT_SENT_BACK","RECEIVED_IN_WAREHOUSE","RETURNED","NOT_RETURNED","OUT_FOR_DELIVERY","DELIVERY_EXCEPTION","SUBMITTED","CANCELLED","CONFIRMED","NOT_COMPLETED","PARTIALLY_COMPLETED"],"example":"APPROVED"},"createdAt":{"type":["string","null"],"format":"date","description":"Calendar date the order was created (organization-local date, same basis as internal order lists).","example":"2026-05-01"}},"required":["id","status"]},"PersonInfo":{"type":"object","description":"Person fields tailored to the new-joiner dashboard view. See GET /api/people/{id} for the canonical, richer Person representation.","properties":{"id":{"type":"string","format":"uuid","description":"Person ID"},"firstName":{"type":"string","description":"First name","example":"Jane"},"lastName":{"type":"string","description":"Last name","example":"Doe"},"email":{"type":"string","description":"Primary email","example":"jane@example.com"},"startDate":{"type":["string","null"],"format":"date","description":"Start date with the organization","example":"2026-05-01"},"countryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code (from the person's address)","example":"US"},"status":{"type":"string","description":"Person lifecycle status","enum":["INVITED","ACTIVE","INACTIVE","DELETED","OFFBOARDING","CANNOT_REACTIVATE"],"example":"INVITED"}},"required":["email","firstName","id","lastName","status"]},"PublicAPINewJoinerLastReminderResponse":{"type":"object","description":"Last reminder sent to the new joiner","properties":{"sentAt":{"type":"string","format":"date-time","description":"When the reminder was sent"},"sentByPersonId":{"type":"string","format":"uuid","description":"Person ID of who sent the reminder, null if triggered via API"}},"required":["sentAt"]},"PublicAPINewJoinerRowResponse":{"type":"object","description":"A single row in the new joiner provisioning pipeline.","properties":{"person":{"$ref":"#/components/schemas/PersonInfo","description":"The person (new joiner) this onboarding row belongs to."},"equipmentReadiness":{"type":"string","description":"Indicates whether the equipment for this new joiner is ready for deployment.","enum":["NOT_STARTED","ORDER_PLACED","READY"]},"orderRef":{"type":"null","$ref":"#/components/schemas/OrderRef","description":"Lightweight reference to this new joiner's equipment provisioning order (maps to the internal GraphQL `order` field). Null when the joiner has not been ordered yet; use GET /api/orders/{id} for full order details."},"urgency":{"type":["string","null"],"description":"Urgency classification for this new joiner's equipment pipeline. ON_TRACK, AT_RISK, or LATE when the pipeline is still in progress. Null once provisioningOutcome is set — the pipeline has resolved and urgency no longer applies.","enum":["ON_TRACK","AT_RISK","LATE"]},"provisioningOutcome":{"type":["string","null"],"description":"The outcome of the equipment provisioning process for this new joiner.","enum":["ON_TIME","LATE"]},"provisioningOutcomeDate":{"type":["string","null"],"format":"date","description":"Calendar date when equipment was delivered (order path) or inventory was assigned (inventory path). Same date the backend used to compute provisioningOutcome. Null when equipmentReadiness is not READY or no date could be derived.","example":"2026-05-01"},"provisioningOutcomeSource":{"type":["string","null"],"description":"Identifies which data source produced provisioningOutcomeDate. ORDER_DELIVERY: date comes from the latest deliveryDate on a computer order line. INVENTORY_ASSIGNMENT: date comes from the audit-derived deployedAt for deployed computer inventory. Null when provisioningOutcomeDate is null.","enum":["ORDER_DELIVERY","INVENTORY_ASSIGNMENT"]},"estimatedDeliveryDate":{"type":["string","null"],"format":"date","description":"The estimated date on which the new joiner's equipment will be delivered."},"lastReminder":{"type":"null","$ref":"#/components/schemas/PublicAPINewJoinerLastReminderResponse","description":"The date and time the last onboarding reminder notification was sent."},"reminderCount":{"type":"integer","format":"int32","description":"The total number of onboarding reminder notifications sent for this new joiner."},"procurementMethod":{"type":["string","null"],"description":"How this new joiner's equipment is fulfilled. WAREHOUSE when all computer lines are sourced from inventory, DROPSHIP when all are shipped directly from a vendor, MIXED when both methods are used. Null when no computer lines have a fulfilment record yet.","enum":["WAREHOUSE","DROPSHIP","MIXED"]},"assignedPackage":{"type":"null","$ref":"#/components/schemas/AssignedPackage","description":"First package assigned to this person. Null when unassigned. When a person has more than one package, this is the first one, matching the People CSV."}},"required":["equipmentReadiness","person","reminderCount"]},"AvailabilityDTO":{"type":"object","properties":{"condition":{"type":"string","description":"The condition of the item","example":"NEW or USED"},"count":{"type":"integer","format":"int32","description":"The number of available items in this condition","example":1}},"required":["condition","count"]},"ProductPriceDetails":{"type":"object","properties":{"regionCode":{"type":"string","description":"Region where this product is available","example":"EU"},"priceOption":{"type":"string","description":"The billing type","example":"Subscription or Purchased"},"price":{"type":["number","null"],"description":"The price. Null when firstbaseManaged is true (vendor pricing).","example":123.45},"currencyCode":{"type":"string","description":"The currency code for the price","example":"EUR"},"countryCodes":{"type":"array","description":"The country codes for this region","examples":["DE","FR"],"items":{"type":"string"}},"firstBaseSupplied":{"type":"boolean","description":"Tells if SKU is Firstbase supplied","example":true},"firstbaseManaged":{"type":"boolean","description":"True when this price row is Firstbase Managed for the caller's organization (FM region and Firstbase supplied). When true, price is omitted (vendor pricing).","example":false}},"required":["countryCodes","currencyCode","firstBaseSupplied","firstbaseManaged","priceOption","regionCode"]},"SimplifiedProductItemDTO":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"SKU's internal ID","example":"123E4567-E89B-12D3-A456-426614174000"},"imageUrl":{"type":["string","null"],"description":"Presigned URL for the product image","example":"https://bucket.s3.amazonaws.com/image.jpg?X-Amz-Expires=86400"},"title":{"type":"string","description":"SKU's title","example":"MacBook Air 13\" M3 8-Core CPU 10-Core GPU 8GB RAM 512GB SSD - US / English - Space Gray - AU Plug"},"vendorSku":{"type":"string","description":"SKU's vendor SKU value","example":"123E4567-E89B-12D3-A456-426614174000"},"vendorCode":{"type":"string","description":"SKU's vendor's code","example":"APPLE"},"partNumber":{"type":"string","description":"SKU's part number","example":"MZ-1234HG"},"isStandardCatalog":{"type":"boolean","description":"Tells if the SKU is part of org's standard catalog","example":true},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"SKU's structured metadata"},"pricing":{"type":"array","description":"SKU's pricing details","items":{"$ref":"#/components/schemas/ProductPriceDetails"}},"stock":{"type":"array","description":"List of regions where this product is available","items":{"$ref":"#/components/schemas/StockDetailsDTO"}},"categoryCode":{"type":"string","description":"The category code for this product","example":"COMPUTER"},"categoryNameOfSku":{"type":"string","description":"The category name for this product","example":"Computer"}},"required":["categoryCode","categoryNameOfSku","id","isStandardCatalog","metadata","pricing","stock","title","vendorCode","vendorSku"]},"StockDetailsDTO":{"type":"object","properties":{"regionCode":{"type":"string","description":"Region where this product is available","example":"EU"},"countryCodes":{"type":"array","description":"List of countries where this product is available","examples":["DE","FR"],"items":{"type":"string"}},"availability":{"type":"array","description":"List of stock  availability details","items":{"$ref":"#/components/schemas/AvailabilityDTO"}}},"required":["availability","countryCodes","regionCode"]},"CarrierTypeDto":{"type":"object","properties":{"carrier":{"type":"string","description":"The carrier code to use with shipment tracking requests","example":"UPS"},"displayName":{"type":"string","description":"Carrier display name","example":"UPS"}},"required":["carrier","displayName"]},"ShipmentNoticeOrderResponse":{"type":"object","description":"Shipment notice order","properties":{"id":{"type":"string","format":"uuid","description":"Shipment notice order ID"},"status":{"type":"string","description":"Order status","enum":["SUBMITTED","PROCESSING","COMPLETED","PARTIALLY_COMPLETED","NOT_COMPLETED","CANCELLED"]},"sourceType":{"type":"string","description":"Source type","enum":["SUPPLIER","OFFICE"]},"condition":{"type":"string","description":"Condition of items","enum":["NEW","USED"]},"purchaseOrderNumber":{"type":"string","description":"Purchase order number"},"expectedShipDate":{"type":"string","format":"date","description":"Expected ship date"},"createdAt":{"type":"string","format":"date-time","description":"Created timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last updated timestamp"},"warehouse":{"$ref":"#/components/schemas/WarehouseRef","description":"Destination warehouse"},"shipmentNoticeOrderItems":{"type":"array","description":"Order line items","items":{"$ref":"#/components/schemas/ShipmentNoticeOrderItemResponse"}},"shipmentNoticePackages":{"type":"array","description":"Packages in this shipment notice","items":{"$ref":"#/components/schemas/ShipmentNoticePackageResponse"}},"submittedBy":{"type":"null","$ref":"#/components/schemas/PublicApiPersonRef","description":"Person who submitted the shipment notice."}},"required":["createdAt","id","shipmentNoticeOrderItems","shipmentNoticePackages","sourceType","status","updatedAt","warehouse"]},"ShipmentNoticePackageItemResponse":{"type":"object","description":"Shipment notice package item","properties":{"id":{"type":"string","format":"uuid","description":"Package item ID"},"status":{"type":"string","description":"Package item status","enum":["EXPECTED","RECEIVED","PARTIALLY_RECEIVED","OVER_RECEIVED","NOT_RECEIVED","CANCELLED"]},"expectedQuantity":{"type":"integer","format":"int32","description":"Expected quantity"},"receivedQuantity":{"type":"integer","format":"int32","description":"Received quantity"},"createdAt":{"type":"string","format":"date-time","description":"Created timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last updated timestamp"},"skuId":{"type":"string","format":"uuid","description":"SKU ID for this package item"},"vendorSku":{"type":"string","description":"Vendor SKU code"},"serialNumber":{"type":"string","description":"Serial number from inventory association"}},"required":["createdAt","id","updatedAt"]},"ShipmentNoticePackageResponse":{"type":"object","description":"Shipment notice package","properties":{"id":{"type":"string","format":"uuid","description":"Package ID"},"status":{"type":"string","description":"Package status","enum":["PENDING","IN_TRANSIT","OUT_FOR_DELIVERY","ARRIVED_AT_PROCESSING_FACILITY","PARTIALLY_RECEIVED","FULLY_RECEIVED","OVER_RECEIVED","NOT_RECEIVED","CANCELLED","DELIVERY_EXCEPTION"]},"trackingCode":{"type":"string","description":"Tracking code"},"shippingCarrier":{"type":"string","description":"Shipping carrier"},"trackingUrl":{"type":"string","description":"Tracking URL"},"createdAt":{"type":"string","format":"date-time","description":"Created timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last updated timestamp"},"shipmentNoticePackageItems":{"type":"array","description":"Package items","items":{"$ref":"#/components/schemas/ShipmentNoticePackageItemResponse"}}},"required":["createdAt","id","shipmentNoticePackageItems","updatedAt"]}},"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Prefix the value with \"ApiKey\" to indicate the custom authorization type","name":"Authorization","in":"header"}}}}