> ## 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. # Modify an existing order > Partially update an existing order. Allowed before fulfilment. Modifiable fields: products, shippingAddress, deliverToPersonId, deliverToOfficeId, status (CANCELLED only). 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. ## OpenAPI ````yaml /openapi.json patch /api/v1/orders/{orderId} 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/orders/{orderId}: patch: tags: - Orders summary: Modify an existing order description: >- Partially update an existing order. Allowed before fulfilment. Modifiable fields: products, shippingAddress, deliverToPersonId, deliverToOfficeId, status (CANCELLED only). 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: '200': description: Order updated content: application/json: schema: $ref: '#/components/schemas/PublicAPIGetOrderResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/PublicApiHttpErrors' '403': description: Endpoint not available for this org content: application/json: schema: $ref: '#/components/schemas/PublicApiHttpErrors' '404': description: Order not found 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' components: schemas: PublicAPIPatchOrderRequest: type: object description: >- Request body for modifying an existing order. All fields are optional. Omit a field to leave it unchanged. 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: $ref: '#/components/schemas/JsonNullableListPublicAPIPatchOrderItem' 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. shippingAddress: $ref: '#/components/schemas/JsonNullablePublicAPIUpdateShippingAddress' description: New shipping address (full replace). deliverToPersonId: $ref: '#/components/schemas/JsonNullableUUID' 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: $ref: '#/components/schemas/JsonNullableUUID' 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: $ref: '#/components/schemas/JsonNullablePublicAPIPatchOrderStatus' description: >- New status. Only CANCELLED is accepted. Omit the field to leave status unchanged; explicit null is invalid. required: - deliverToOfficeId - deliverToPersonId - products - shippingAddress - status 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 - 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: 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: $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 format: date-time description: UTC ISO-8601 timestamp when the order was created. example: '2026-02-26T14:15:22.123Z' updatedAt: type: string format: date-time description: UTC ISO-8601 timestamp when the order was last updated. example: '2026-03-15T09:00:00.000Z' expectedBy: type: string 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 description: Slug of the product package this order was created from, if any. example: engineering-onboarding deliveryLocation: type: string 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 PublicApiHttpErrors: type: object properties: errors: type: array items: $ref: '#/components/schemas/PublicApiError' required: - errors JsonNullableListPublicAPIPatchOrderItem: type: object properties: present: type: boolean JsonNullablePublicAPIUpdateShippingAddress: type: object properties: present: type: boolean JsonNullableUUID: type: object properties: present: type: boolean JsonNullablePublicAPIPatchOrderStatus: type: object properties: present: type: boolean 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 - 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 statusHistory: type: array description: Chronological history of status changes items: $ref: '#/components/schemas/StatusHistoryEntry' fulfillmentMethod: type: string description: Order item's fulfillment method enum: - WAREHOUSE - DROPSHIP vendorSku: type: string 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 description: >- Vendor code of the SKU's vendor. Populated only when the SKU's vendor is known. example: APPLE serialNumber: type: string description: Serial number assigned to this order item, if any. example: C02XL0AAJG5L justification: type: string description: Justification text recorded for this order item, if any. example: Need higher RAM for local development workflows purchaseOrderNumber: type: string description: >- Regional purchase order number stamped on this order item when applicable. example: PO-US-LAPTOPS-001 required: - categoryCode - id - skuId - status - statusHistory - title 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 - 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: APPROVED timestamp: type: string format: date-time description: Timestamp of status change in UTC example: '2023-01-01T12:00:00Z' required: - status - timestamp AddressInfo: type: object properties: addressLine1: type: string example: 123 addressLine2: type: string 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 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 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 ````