> ## Documentation Index > Fetch the complete documentation index at: https://developers.firstbase.com/llms.txt > Use this file to discover all available pages before exploring further. # Modify or cancel an existing order > Partially update an existing order. Allowed before fulfilment. All request body fields are optional — omit any field to leave it unchanged. **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`. Other 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. ## OpenAPI ````yaml /openapi.json patch /api/v1/orders/{orderId} openapi: 3.1.0 info: title: Firstbase API Specification description: Integration endpoints for Firstbase version: 0.1.0 servers: - url: https://apipub.firstbasehq.com description: Production security: - ApiKey: [] tags: - name: Catalog description: Browse SKUs, brands, and categories - name: Inventory description: Query and manage inventory items and assets - name: Inventory Levels description: Configure inventory levels by SKU and warehouse - name: Inventory Orders description: Create and manage inventory orders - name: ITAD description: IT asset disposition requests - name: New Joiners description: Track and remind new joiners - name: Offices description: Manage office locations - name: Orders description: Create and track equipment orders - name: Packages description: Manage equipment packages - name: People description: Provision and manage users - name: Regions description: Query regions - name: Replacements description: Create and manage equipment replacements - name: Returns description: Create and manage returns - name: Shipment description: Look up shipments and carriers - name: Shipment Notices description: Create and manage shipment notices - name: Warehouses description: Query warehouses paths: /api/v1/orders/{orderId}: 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. **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`. Other 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' example: products: [] shippingAddress: addressLine1: 123 addressLine2: Apartment B administrativeArea: California countryCode: US dependentLocality: Mission Bay locality: San Francisco postalCode: 94158 sortingCode: 94158-1234 phoneNumber: +1-415-555-1234 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' x-codeSamples: - lang: curl label: cURL source: >- curl -sS -X PATCH 'https://apipub.firstbasehq.com/api/v1/orders/{orderId}' \ -H 'Authorization: ApiKey YOUR_API_KEY' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "products": [], "shippingAddress": { "addressLine1": 123, "addressLine2": "Apartment B", "administrativeArea": "California", "countryCode": "US", "dependentLocality": "Mission Bay", "locality": "San Francisco", "postalCode": 94158, "sortingCode": "94158-1234", "phoneNumber": "+1-415-555-1234" } }' components: schemas: 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 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 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: $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' description: List of error details. required: - errors 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 format: uuid description: >- Existing order item id when updating that line's expedited shipping or preferred condition. cancelled: type: boolean description: If true, cancel this line. Requires `id`. Defaults to false. vendorSku: type: string description: >- Vendor SKU when adding a new line (required together with vendorCode). vendorCode: type: string description: >- Vendor code when adding a new line (required together with vendorSku). expeditedShippingOption: type: string description: >- Expedited shipping for this line. Allowed: EXPEDITED_STANDARD. Explicit null clears. enum: - EXPEDITED_STANDARD preferredCondition: type: string description: 'Physical condition for this line. Allowed values: NEW, USED.' enum: - NEW - USED justification: type: string description: >- Order-item justification text. Omit to leave unchanged; explicit null is treated as unchanged. intendedFulfillmentMethod: type: string 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 PublicAPIUpdateShippingAddress: type: object description: Shipping address for an order modification request properties: addressLine1: type: string description: The primary line of the address (e.g., house number and street name) example: 123 addressLine2: type: string description: Additional address information (e.g., apartment or suite number) example: Apartment B administrativeArea: type: string 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 description: >- A smaller subdivision within the locality, often used for neighborhoods or districts example: Mission Bay locality: type: string description: The city or town within the administrative area example: San Francisco postalCode: type: string description: The ZIP code or equivalent postal code example: 94158 sortingCode: type: string description: >- A code used for routing or sorting mail, often specific to postal systems. example: 94158-1234 phoneNumber: type: string description: A contact phone number, including the international dialing code example: +1-415-555-1234 required: - countryCode 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 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 type: type: string 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 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: $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 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 orderedWarrantyItem: 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. required: - categoryCode - id - skuId - status - statusHistory - title firstbaseManaged: type: boolean 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. 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 - 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 AddressInfo: type: object properties: addressLine1: type: string description: Street address line 1 example: 123 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 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' 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 format: uuid description: Catalog pricing row id example: 123E4567-E89B-12D3-A456-426614174000 unitPrice: type: number description: Unit price in major currency units example: 999 currencyCode: type: string description: ISO 4217 currency code example: USD 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 ````