> ## Documentation Index > Fetch the complete documentation index at: https://developer.firstbasedev.com/llms.txt > Use this file to discover all available pages before exploring further. # Process return items > 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. ## OpenAPI ````yaml /openapi.json patch /api/v1/return-orders/{returnOrderId}/items 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: 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: /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 parameters: - name: returnOrderId in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/PublicAPIPatchReturnOrderItemsRequest' required: true responses: '200': description: Items updated content: application/json: schema: $ref: '#/components/schemas/PublicAPIPatchReturnOrderItemsResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/PublicApiHttpErrors' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/PublicApiHttpErrors' '404': description: Return order or item not found content: application/json: schema: $ref: '#/components/schemas/PublicApiHttpErrors' '409': description: Conflict content: '*/*': schema: $ref: '#/components/schemas/PublicApiHttpErrors' components: schemas: 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 isUniqueItemIds: type: boolean required: - isUniqueItemIds - items 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 PublicApiHttpErrors: type: object properties: errors: type: array items: $ref: '#/components/schemas/PublicApiError' required: - errors 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 isOtherReasonDetailed: type: boolean isDispositionRequiredWhenNotReturned: type: boolean isDeployFieldsOnlyWhenNotReturned: type: boolean isDeployFieldsAbsentWhenDeployed: type: boolean isDeployReasonPresentWhenArchive: type: boolean isDeployReasonDetailsOnlyForOther: type: boolean isDispositionAbsentWhenReturned: type: boolean required: - id - isDeployFieldsAbsentWhenDeployed - isDeployFieldsOnlyWhenNotReturned - isDeployReasonDetailsOnlyForOther - isDeployReasonPresentWhenArchive - isDispositionAbsentWhenReturned - isDispositionRequiredWhenNotReturned - isOtherReasonDetailed - status 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 - NONE - APPROVED - AWAITING_FULFILLMENT - 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 description: Vendor's own SKU identifier. example: APL-MK183LL/A vendorCode: type: string description: Vendor short code. example: APPLE serialNumber: type: string description: Serial number assigned to the inventory unit, if any. holdRequested: type: boolean 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 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 PublicAPIOrderItemShipmentResponse: type: object properties: trackingUrl: type: string 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 securitySchemes: ApiKey: type: apiKey description: Prefix the value with "ApiKey" to indicate the custom authorization type name: Authorization in: header ````