> ## Documentation Index > Fetch the complete documentation index at: https://docs.polinate.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update an order and manage order items (comprehensive CRUD) > Comprehensive order updates supporting: - Core order fields (phase, status, externalReference, notes, deliveryAddress, dates, currency, totalAmount, properties) - Create, update, and delete operations for order items **Order Items:** Each order item references an item list entry (via itemListEntryId). An order can only have one item per item list entry (enforced by unique constraint). **Properties (JSONB) - Upsert Behavior:** - Properties are **deep merged**, not replaced - Top-level keys (e.g., "sage200Evo", "unleashed") are merged preserving other providers - Nested fields within a provider are also merged (e.g., adding "invoiceNo" preserves existing "salesOrderNo") - `null` is a valid value and will NOT delete keys - To delete a property section, fetch the order, modify the properties object, and send the complete modified object **Example:** If an order has `{ unleashed: { guid: "123" } }` and you PATCH with `{ sage200Evo: { salesOrderNo: 456 } }`, the result is `{ unleashed: { guid: "123" }, sage200Evo: { salesOrderNo: 456 } }`. **Field Descriptions:** - **phase**: High-level lifecycle state (DRAFT, PENDING, DELETED, ACTIVE, ARCHIVED, REJECTED, CANCELLED) - **status**: Physical fulfillment/movement state (UNASSIGNED, ACCEPTED, PACKED, IN_TRANSIT, DELIVERED, RETURNED, NOT_APPLICABLE) - All datetime fields should be ISO 8601 format (e.g., "2025-01-15T10:30:00.000Z") ## OpenAPI ````yaml openapi.json patch /api/v1/orders/{id} openapi: 3.0.3 info: title: Polinate External API version: 1.0.0 description: >- External API for partners and services. Authentication via X-Business-Id and X-API-Key headers. Credentials location: In the Polinate app, navigate to Business Settings → Integrations to find your Business ID and API Key. servers: - url: https://integrations.polinate.ai description: Production security: [] tags: - name: Items description: >- Manage items and item variants. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Buyers description: >- Create buyers and related contacts/locations. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Pricing description: >- Create price lists and entries. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Invoices description: >- List and update invoices. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Orders description: >- Order ingestion. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). paths: /api/v1/orders/{id}: patch: tags: - Orders summary: Update an order and manage order items (comprehensive CRUD) description: >- Comprehensive order updates supporting: - Core order fields (phase, status, externalReference, notes, deliveryAddress, dates, currency, totalAmount, properties) - Create, update, and delete operations for order items **Order Items:** Each order item references an item list entry (via itemListEntryId). An order can only have one item per item list entry (enforced by unique constraint). **Properties (JSONB) - Upsert Behavior:** - Properties are **deep merged**, not replaced - Top-level keys (e.g., "sage200Evo", "unleashed") are merged preserving other providers - Nested fields within a provider are also merged (e.g., adding "invoiceNo" preserves existing "salesOrderNo") - `null` is a valid value and will NOT delete keys - To delete a property section, fetch the order, modify the properties object, and send the complete modified object **Example:** If an order has `{ unleashed: { guid: "123" } }` and you PATCH with `{ sage200Evo: { salesOrderNo: 456 } }`, the result is `{ unleashed: { guid: "123" }, sage200Evo: { salesOrderNo: 456 } }`. **Field Descriptions:** - **phase**: High-level lifecycle state (DRAFT, PENDING, DELETED, ACTIVE, ARCHIVED, REJECTED, CANCELLED) - **status**: Physical fulfillment/movement state (UNASSIGNED, ACCEPTED, PACKED, IN_TRANSIT, DELIVERED, RETURNED, NOT_APPLICABLE) - All datetime fields should be ISO 8601 format (e.g., "2025-01-15T10:30:00.000Z") operationId: updateOrder parameters: - schema: type: string example: ord_123 required: true name: id in: path - schema: type: string description: >- Business identifier for external auth. Find in Polinate app → Business Settings → Integrations. example: '{{businessId}}' required: true name: X-Business-Id in: header - schema: type: string description: >- Per-business API key for external auth. Find in Polinate app → Business Settings → Integrations. example: '{{apiKey}}' required: true name: X-API-Key in: header - schema: type: string description: Idempotency key for POST operations example: '{{idempotencyKey}}' required: false name: Idempotency-Key in: header requestBody: content: application/json: schema: $ref: '#/components/schemas/OrderUpdateRequest' examples: SimpleUpdate: summary: Update core order fields value: order: phase: ACTIVE status: PACKED externalReference: PO-2025-001 notes: Confirmed and ready for shipment PropertiesUpsert: summary: Add/update properties (deep merge) value: order: properties: sage200Evo: salesOrderNo: 12345 CreateOrderItems: summary: Add new order items value: createOrderItems: - itemListEntryId: ile_abc123 quantity: 10 unitOfMeasure: Each currency: AUD price: 25 cost: 15 lineNumber: 1 - itemListEntryId: ile_def456 quantity: 5 unitOfMeasure: Box currency: AUD price: 50 cost: 30 lineNumber: 2 UpdateOrderItems: summary: Update existing order items value: updateOrderItems: - id: oi_123 quantity: 15 price: 22.5 - id: oi_456 unitOfMeasure: Pallet cost: 28 DeleteOrderItems: summary: Remove order items value: deleteOrderItems: - oi_123 - oi_456 ShippingUpdate: summary: Update order with shipping information value: order: phase: ACTIVE status: IN_TRANSIT shippedAt: '2025-01-15T14:30:00.000Z' expectedDeliveryAt: '2025-01-17T09:00:00.000Z' notes: Shipped via express courier FullUpdate: summary: Update order fields and manage items in one request value: order: phase: ACTIVE status: PACKED externalReference: PO-2025-XYZ notes: Packed and ready for pickup deliveryAddress: 123 Business St, Sydney NSW 2000 expectedDeliveryAt: '2025-01-20T10:00:00.000Z' currency: AUD totalAmount: 1250.5 properties: warehouseZone: A3 priority: high createOrderItems: - itemListEntryId: ile_new123 quantity: 20 unitOfMeasure: Each currency: AUD price: 15 cost: 9 updateOrderItems: - id: oi_existing quantity: 25 price: 14.5 deleteOrderItems: - oi_obsolete responses: '200': description: OK - Returns full updated order with all items content: application/json: schema: $ref: '#/components/schemas/Order' example: id: ord_123 phase: ACTIVE status: PACKED externalReference: PO-2025-001 orderItems: - id: oi_1 itemVariantId: var_abc quantity: 10 unitAmount: 25 currency: AUD '400': description: Invalid payload or duplicate order item content: application/json: schema: $ref: '#/components/schemas/StandardError' examples: ValidationError: summary: Invalid enum value value: errorCode: VALIDATION_ERROR message: >- Some information looks incorrect. Please review the highlighted fields. fieldErrors: order.phase: Invalid enum value DuplicateOrderItem: summary: Duplicate item list entry value: error: >- One or more order items already exist for this order. An order can only have one item per item list entry. EmptyPayload: summary: No valid fields provided value: error: No valid fields provided for update '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/StandardError' '403': description: Forbidden - Order does not belong to this business content: application/json: schema: $ref: '#/components/schemas/StandardError' example: error: Order does not belong to this business '404': description: Not Found - Order or order item not found content: application/json: schema: $ref: '#/components/schemas/StandardError' examples: OrderNotFound: summary: Order does not exist value: error: Order not found OrderItemNotFound: summary: Order item ID not found value: error: 'Order item(s) not found: oi_123, oi_456' '429': description: Rate limited headers: Retry-After: schema: type: string description: Seconds to wait before retrying content: application/json: schema: $ref: '#/components/schemas/StandardError' components: schemas: OrderUpdateRequest: type: object properties: order: type: object properties: phase: type: string enum: - DRAFT - PENDING - DELETED - ACTIVE - ARCHIVED - REJECTED - CANCELLED status: type: string enum: - UNASSIGNED - ACCEPTED - PACKED - IN_TRANSIT - DELIVERED - RETURNED - NOT_APPLICABLE externalReference: type: string nullable: true notes: type: string nullable: true deliveryAddress: type: string nullable: true expectedDeliveryAt: type: string format: date-time shippedBy: type: string nullable: true format: date-time shippedAt: type: string nullable: true format: date-time deliveredAt: type: string nullable: true format: date-time currency: type: string enum: - USD - EUR - GBP - CAD - AUD - NZD - CHF - JPY - CNY - INR - BRL - MXN - ARS - COP - PHP totalAmount: type: number properties: type: object properties: {} additionalProperties: false createOrderItems: type: array items: type: object properties: itemListEntryId: type: string description: Must reference an existing item list entry quantity: type: number unitOfMeasure: type: string currency: type: string enum: - USD - EUR - GBP - CAD - AUD - NZD - CHF - JPY - CNY - INR - BRL - MXN - ARS - COP - PHP price: type: number cost: type: number lineNumber: type: number properties: type: object properties: {} required: - itemListEntryId - quantity - unitOfMeasure - currency - price - cost updateOrderItems: type: array items: type: object properties: id: type: string quantity: type: number unitOfMeasure: type: string currency: type: string enum: - USD - EUR - GBP - CAD - AUD - NZD - CHF - JPY - CNY - INR - BRL - MXN - ARS - COP - PHP price: type: number cost: type: number lineNumber: type: number properties: type: object properties: {} required: - id deleteOrderItems: type: array items: type: string additionalProperties: false Order: type: object properties: id: type: string partnershipId: type: string description: The business partnership this order belongs to membershipId: type: string nullable: true integrationId: type: string nullable: true phase: type: string enum: - DRAFT - PENDING - DELETED - ACTIVE - ARCHIVED - REJECTED - CANCELLED status: type: string enum: - UNASSIGNED - ACCEPTED - PACKED - IN_TRANSIT - DELIVERED - RETURNED - NOT_APPLICABLE internalReference: type: string externalReference: type: string nullable: true notes: type: string nullable: true deliveryAddress: type: string nullable: true expectedDeliveryAt: type: string format: date-time deliveredAt: type: string nullable: true format: date-time shippedAt: type: string nullable: true format: date-time currency: type: string totalAmount: type: string description: Decimal as string properties: type: object nullable: true properties: {} createdAt: type: string format: date-time updatedAt: type: string format: date-time orderItems: type: array items: $ref: '#/components/schemas/OrderItem' required: - id - partnershipId - internalReference - expectedDeliveryAt - currency - totalAmount - createdAt - updatedAt StandardError: type: object properties: errorCode: type: string message: type: string fieldErrors: type: object additionalProperties: type: string required: - errorCode - message OrderItem: type: object properties: id: type: string orderId: type: string lineNumber: type: number itemListEntryId: type: string itemListEntry: type: object properties: itemVariantId: type: string itemVariant: type: object properties: itemId: type: string required: - itemId required: - itemVariantId - itemVariant quantity: type: number unitOfMeasure: type: string currency: type: string price: type: string description: Decimal as string cost: type: string description: Decimal as string properties: type: object nullable: true properties: {} createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - orderId - lineNumber - itemListEntryId - itemListEntry - quantity - unitOfMeasure - currency - price - cost - createdAt - updatedAt ````