> ## Documentation Index > Fetch the complete documentation index at: https://developers.openborder.com/llms.txt > Use this file to discover all available pages before exploring further. # Update an order > ## What this endpoint does Use this endpoint to update a previously submitted order. Order will be matched by the `source_reference` field. Supported updates may include order and shipment status changes, shipment product changes (for example refunds, product changes or new shipments added), or corrections to customer addresses. ## OpenAPI ````yaml /api-reference/landed-cost.json put /v1/orders openapi: 3.0.0 info: title: OpenBorder Direct API Service description: Direct API Service description for OPEN API documentation version: '0.1' contact: {} servers: - url: https://api.openborder.com/api/direct/ description: Production - url: https://api.staging.openborder.com/api/direct/ description: Sandbox security: [] tags: [] paths: /v1/orders: put: tags: - Orders summary: Update an order description: >- ## What this endpoint does Use this endpoint to update a previously submitted order. Order will be matched by the `source_reference` field. Supported updates may include order and shipment status changes, shipment product changes (for example refunds, product changes or new shipments added), or corrections to customer addresses. operationId: OrdersController_updateOrder parameters: - name: x-openborder-direct-api-key in: header description: OpenBorder merchant API token required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderUpdatePayload' responses: '204': description: Order successfully updated. No content returned. '400': description: Invalid order payload received. '401': description: Invalid authorization token received. '422': description: Order data failed validation rules. content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityException' components: schemas: OrderUpdatePayload: type: object properties: source_reference: type: number description: >- Reference ID from the source system. This is the unique identifier to reference the order on subsequent calls and cannot be updated. source_updated_at: type: string description: >- Timestamp in ISO format when the order was last updated in the source system. ship_to: description: Address to which the order is shipped. allOf: - $ref: '#/components/schemas/ShipToAddress' billing_address: description: Billing address for the order. allOf: - $ref: '#/components/schemas/BillingAddress' order_discount: type: number description: >- Total order-level discount in major currency units (e.g., 10.00 means $10 off). Discount is split proportionally across products for duties/taxes. shipments: description: >- A shipment groups the items sent from a specific origin warehouse to the order's destination address. While a shipment originates from one location, it can be fulfilled in multiple batches (`fulfillments`), each potentially having a different tracking number, ship date, and carrier. To add a new shipment, provide a new shipment object with a new `shipment_id` type: array items: $ref: '#/components/schemas/OrderUpdateShipmentRequest' custom_properties: type: object description: >- Optional custom metadata or structured properties. Object max. size is 4 KB. nullable: true required: - source_reference - source_updated_at UnprocessableEntityException: type: object properties: error: description: Validation errors type: array items: $ref: '#/components/schemas/ErrorDetails' ShipToAddress: type: object properties: country_code: type: string description: >- The two-letter country code (ISO 3166-1 alpha-2) for the destination country (e.g. "CA" for Canada). Important: For United States of America (US) and Canada (CA) the `province` and `postal_code` fields are required. province: type: string description: >- The state, province, or region within the destination country. Include this if your destination country has one (e.g."ON" for Ontario). Important: Required for United States of America (US) and Canada (CA). nullable: true postal_code: type: string description: >- The ZIP code or postal code for the shipping address. Important: Required for United States of America (US) and Canada (CA). nullable: true address1: type: string description: >- The primary street address line, such as the house number and street name. Example: "123 Main Street". nullable: true address2: type: string description: >- A secondary address line, such as an apartment, suite, or unit number. Example: "Apt 4B". nullable: true city: type: string description: The city or locality for the delivery address. nullable: true name: type: string description: The full name of the recipient at the destination address. nullable: true required: - country_code BillingAddress: type: object properties: country_code: type: string description: >- The two-letter country code (ISO 3166-1 alpha-2) for the billing address (e.g. "CA" for Canada). province: type: string description: >- The state, province, or region within the billing country. Include this if your billing country has one (e.g."ON" for Ontario). nullable: true postal_code: type: string description: The ZIP code or postal code for the billing address. nullable: true address1: type: string description: >- The primary street address line for billing, such as the house number and street name. Example: "123 Main Street". nullable: true address2: type: string description: >- A secondary billing address line, such as an apartment, suite, or unit number. Example: "Apt 4B". nullable: true city: type: string description: The city or locality for the billing address. nullable: true name: type: string description: >- The full name of the person or entity responsible for billing at this address. nullable: true required: - country_code OrderUpdateShipmentRequest: type: object properties: shipment_id: type: string description: >- Unique identifier for shipment. If this ID matches a previously submitted shipment, it will be updated, otherwise a new shipment will be added to the order. ship_from: description: >- Address from which the order is shipped. Will be updated for existing shipments if provided. allOf: - $ref: '#/components/schemas/ShipFromAddress' status: type: string description: >- Current status of the shipment. Will be updated for existing shipments if provided. Important: If `status` is set to `partially_fulfilled` or `fulfilled`, at least one fulfillment must exists under the shipment's `fulfillments` field. enum: - pending - canceled - returned - refunded - partially_fulfilled - fulfilled fulfillments: description: >- Fulfillment batches associated to the shipment. If an existing tracking number is provided for an existing fulfillment, it will be updated, otherwise a new fulfillment will be added to the shipment's fulfillments list. type: array items: $ref: '#/components/schemas/Fulfillment' refunded_amount: type: number description: >- Total amount refunded for the shipment in major currency units (e.g., dollars). Up to two decimal places are allowed. Will be updated for existing shipments if provided. items: description: >- Items included in the shipment. For new items added you must provide all fields. For items update (matches by `source_line_id` field) only `quantity`, `fulfillment_status`, `fulfillments` and `refunded_quantity` fields may be updated. To remove an item set its `quantity` to `0`. type: array items: $ref: '#/components/schemas/OrderItemUpdate' shipping_rate_id: type: string description: A unique ID for the shipping rate option (e.g., "EXPRESS_UPS"). shipping_rate: type: number description: >- The cost of the shipping rate in major currency units (e.g., dollars). Up to two decimal places. required: - shipment_id - shipping_rate_id - shipping_rate ErrorDetails: type: object properties: field: type: string description: Field name example: ship_from error: type: string description: Error message example: Name is required required: - field - error ShipFromAddress: type: object properties: country_code: type: string description: >- The two-letter country code (ISO 3166-1 alpha-2) for the shipping origin (e.g., "US"). province: type: string description: The state, province, or region within the country. nullable: true postal_code: type: string description: The postal or ZIP code for the origin address. nullable: true address1: type: string description: TThe primary street address line (e.g., "123 Warehouse Ave"). nullable: true address2: type: string description: A secondary address line (e.g., unit or suite number). nullable: true city: type: string description: The city or locality for the delivery address. nullable: true name: type: string description: The full name for the shipping origin, if needed for labeling. nullable: true required: - country_code Fulfillment: type: object properties: tracking_number: type: string description: Tracking number from the carrier. location: type: string description: Location from which the item was shipped. carrier: type: string description: Carrier from which the item was shipped. shipped_at: type: string description: Shipped timestamp in ISO format. status: type: string description: Current status of the fulfillment. enum: - pending - in_transit - delivered - failed items: description: Items included in the shipment. type: array items: $ref: '#/components/schemas/FulfillmentItem' required: - tracking_number - status OrderItemUpdate: type: object properties: source_line_id: type: string description: > Your internal unique ID for this specific line item within the order. hs_code: type: string description: >- Optional merchant-provided HS6 code. When provided, used as the basis for landed cost and classification. nullable: true quantity: type: number description: Quantity of the product in the order. unit_price: type: number description: The per-unit price in major currency units (e.g., dollars). unit_discount: type: number description: >- The total discount applied per unit in major currency units. This amount will be deducted from the unit price when calculating duties/taxes. sku: type: string description: The SKU code for the variant. product_name: type: string description: The name of the product (e.g., "Cotton T-Shirt"). variant_name: type: string description: >- A descriptive variant name, such as "Medium / Blue" — identifies the unique combination of attributes. description: type: string description: A clear description of the product. origin_country_code: type: string description: >- ISO 3166-1 alpha-2 country code for where the product was manufactured. category: type: string description: >- The product category or taxonomy for classification (e.g., "Apparel"). requires_shipping: type: boolean description: >- true if the product physically ships; false for digital/non-physical items. weight: description: Weight information for the item. allOf: - $ref: '#/components/schemas/Weight' source_product_id: type: number description: >- Your internal unique ID for the product. If provided, it must match the `source_product_id` initially submitted for the item matching this line `source_line_id`. source_variant_id: type: number description: >- Your internal unique ID for the variant of the product. If provided, it must match the `source_variant_id` initially submitted for the item matching this line `source_line_id`. refunded_quantity: type: number description: Quantity of the item that was refunded. required: - source_line_id FulfillmentItem: type: object properties: source_line_id: type: string description: > Your internal unique ID for this specific line item within the order. source_product_id: type: number description: Your internal unique ID for the product. source_variant_id: type: number description: Your internal unique ID for the variant of the product. hs_code: type: string description: >- Optional merchant-provided HS6 code. When provided, used as the basis for landed cost and classification. nullable: true quantity: type: number description: The number of units of this product in the shipment. required: - source_line_id - source_product_id - source_variant_id - quantity Weight: type: object properties: per_unit: type: number description: Weight per individual item unit. unit: type: string description: Measurement unit for weight (g = grams, lb = pounds). enum: - g - lb required: - per_unit - unit ````