---
title: "Update an order"
description: "Handle the three most common order revision flows: replacing line items, updating custom data, and resealing finalized orders."
canonical: "https://studio.inttegro.com/guides/update-an-order"
format: inttegro-machine-docs/v1
language: "Java"
sdk_version: "v8.3.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/java/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 494
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "curated"
recommended_mcp_tools: ["get_integration_guide","check_integration_readiness","update_order"]
estimated_tokens: 2967
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Read the current order, choose replacement line items, metadata-only change, or explicit resealing, then inspect the returned full order.

### Five questions

#### Q1. Which order states permit an update?

Check the current order before sending [Update an order](https://studio.inttegro.com/machine/java/api/orders.md#update-an-order). The guide covers mutable states such as preparing and requires-payment; do not treat a completed payment as an editable draft.

#### Q2. Does a line-item update merge with existing items?

No. Send the complete intended line-item set; the update replaces the previous collection. Read the existing order first if any item must be preserved.

#### Q3. When does an update require a seal decision?

Economic or payment-configuration changes to a sealed order require an explicit finalize choice. A metadata-only custom-data change can be applied without reopening or resealing by itself. The [Orders contract](https://studio.inttegro.com/machine/java/api/orders.md#update-an-order) defines the accepted parameters.

#### Q4. What should be checked after the mutation?

The endpoint returns the full order; compare line items, metadata, state, and any new seal with the intended revision. [Look up the order](https://studio.inttegro.com/machine/java/api/orders.md#lookup-an-order) when the application needs an independent current-state read.

#### Q5. Which MCP order changes are actually supported?

With an authenticated connection and confirmation, [update_order](https://studio.inttegro.com/machine/java/inttegro-mcp/tools.md#update_order) changes selected mutable fields; supplied line items replace the whole set, while payment configuration and execution are excluded. [finalize_order](https://studio.inttegro.com/machine/java/inttegro-mcp/tools.md#finalize_order) seals a draft separately. Read [get_order](https://studio.inttegro.com/machine/java/inttegro-mcp/tools.md#get_order) before and after.

## Document content

# Update an order

Orders rarely stay perfect after creation. Inventory changes, operations teams attach internal metadata after review, and approved quotes get revised after an invoice has already gone out. This guide shows how to use [Update an order](https://studio.inttegro.com/machine/java/api/orders.md#update-an-order) for the three update flows most teams hit in production without losing payment context or order history.

> Mcp Guide Callout is interactive content. Use the canonical page to view it.

## Prerequisites

- An existing order ID in a mutable state such as `"preparing"` or `"requires_payment"`
- Familiarity with the [Order lifecycle](https://studio.inttegro.com/machine/java/guides/order-lifecycle.md)
- Access to the [Update an order](https://studio.inttegro.com/machine/java/api/orders.md#update-an-order) API reference

## How the update operation behaves

Reach for [Update an order](https://studio.inttegro.com/machine/java/api/orders.md#update-an-order) when you need to:

1. Replace the order's full line item set before payment starts
2. Refresh order-level `customData(…)` without disturbing payment state
3. Revise a sealed order and deliberately reseal it

The endpoint always returns the full order object. If the order is still open, Inttegro applies the change directly. If the order is already sealed and your change affects economics or payment configuration, you must make the seal decision explicit with `finalizeOrder(…)`. Metadata-only `customData(…)` updates are different: Inttegro can apply them without reopening or resealing by itself. The examples below use direct HTTPS calls so you can adopt the endpoint immediately from any stack.

## Scenario 1: replace line items before payment starts

This is the most common order update flow. A customer changes quantities, an item goes out of stock, or you need to add a manual fee before charging. Send the complete new `lineItems(…)` array—Inttegro replaces the previous collection instead of merging it.

**Replace line items — POST /orders/update**

```java
import com.inttegro.Client;
import com.inttegro.orders.OrderUpdateParams;
import java.util.List;
import com.inttegro.orders.OrderLineItemParams;
import com.inttegro.orders.ProductLineItemParams;
import com.inttegro.products.ProductType;
import com.inttegro.prices.PriceParams;
import com.inttegro.money.Currency;
import com.inttegro.orders.FeeLineItemParams;
import com.inttegro.money.AmountParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = OrderUpdateParams.builder()
      .orderId("or_4Jv9wK2LmQ8rT6xP1nY5sC3dF7hB0uA")
      .number("ORDER-2025-041-REV1")
      .lineItems(List.of(
          OrderLineItemParams.product(ProductLineItemParams.builder()
              .name("Warehouse-picked sneaker")
              .type(ProductType.PHYSICAL)
              .quantity(2L)
              .price(PriceParams.of(Currency.GHS, 9500))
              .build()),
          OrderLineItemParams.fee(FeeLineItemParams.builder()
              .label("Delivery fee")
              .amount(AmountParams.of(Currency.GHS, 1500))
              .build())
        ))
      .build();
    var result = client.orders().update(params);
  }
}
```

After the update:

- Inttegro replaces the previous line items completely.
- [`lineItemGroup(…).total(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/orders/Order.html)
  and
  [`payment(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/orders/Order.html)
  are recalculated from the new items.
- The order remains editable because you did not ask Inttegro to seal it.

## Scenario 2: refresh order-level custom data

Many teams update orders after creation just to attach operational metadata: a review channel, approver identity, fulfillment lane, or internal note that should travel with the order. Send the full replacement `customData(…)` object when you want to refresh those fields. This is a metadata-only mutation, so it does not require reopen or reseal by itself.

**Update custom data — POST /orders/update**

```java
import com.inttegro.Client;
import com.inttegro.orders.OrderUpdateParams;
import com.inttegro.CustomData;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = OrderUpdateParams.builder()
      .orderId("or_aR7mK4qP9dT2xW6nC1yV8sJ5bL0fH3u")
      .customData(new CustomData()
          .set("channel", "ops_review")
          .set("edited_by", "merx")
          .set("priority", "high"))
      .build();
    var result = client.orders().update(params);
  }
}
```

After the update:

- Inttegro replaces the top-level [`customData(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/orders/Order.html) object with the new one you provided.
- The order's economic state stays unchanged: totals, line items, and payment amount are preserved.
- Because this is metadata-only, you can use it without reopening a sealed order or resealing it again.

Use this flow for internal annotations that should travel with the order record but must not change what the customer pays. Typical examples include review queues, fulfillment lanes, campaign attribution, and dashboard-only notes.

## Scenario 3: revise a sealed order and reseal it in one request

This is the high-friction case that matters most in production. You already finalized the order and maybe even sent the invoice, then a customer negotiates a change before payment completes. Send the revised fields together with `finalizeOrder(…)`: `true` and Inttegro will reopen the sealed order internally, apply the changes, and reseal it before returning the updated object.

**Revise and reseal — POST /orders/update**

```java
import com.inttegro.Client;
import com.inttegro.orders.OrderUpdateParams;
import java.util.List;
import com.inttegro.orders.OrderLineItemParams;
import com.inttegro.orders.ProductLineItemParams;
import com.inttegro.products.ProductType;
import com.inttegro.prices.PriceParams;
import com.inttegro.money.Currency;
import com.inttegro.orders.FeeLineItemParams;
import com.inttegro.money.AmountParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = OrderUpdateParams.builder()
      .orderId("or_zT5mQ8wL2pR7vK1xN4cD9sF6hB3uJ0y")
      .number("QUOTE-2025-009-REV2")
      .finalizeOrder(true)
      .lineItems(List.of(
          OrderLineItemParams.product(ProductLineItemParams.builder()
              .name("Annual support retainer")
              .type(ProductType.SERVICE)
              .quantity(1L)
              .price(PriceParams.of(Currency.GHS, 120000))
              .build()),
          OrderLineItemParams.fee(FeeLineItemParams.builder()
              .label("Onboarding workshop")
              .amount(AmountParams.of(Currency.GHS, 15000))
              .build())
        ))
      .build();
    var result = client.orders().update(params);
  }
}
```

After the update:

- Inttegro recalculates the order total and payment amount from the revised items.
- [`sealedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/orders/Order.html) is
  refreshed because the order was sealed again.
- [`invoice(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/orders/Order.html) is
  regenerated so the latest hosted checkout and PDF reflect the revised
  commercial terms.

If you want the order to stay open for more manual edits, send the same mutation with `finalizeOrder(…)`: `false` instead. Inttegro will reopen the sealed order and clear the active invoice until you seal it again with [Finalize an order](https://studio.inttegro.com/machine/java/api/orders.md#finalize-an-order) or another [Update an order](https://studio.inttegro.com/machine/java/api/orders.md#update-an-order) call.

## Related resources

- [Update an order](https://studio.inttegro.com/machine/java/api/orders.md#update-an-order) - Complete endpoint reference
- [Create an order](https://studio.inttegro.com/machine/java/api/orders.md#create-an-order) - Create orders that you may revise later
- [Custom Data](https://studio.inttegro.com/machine/java/api/custom-data.md) - Design metadata shapes for operational annotations
- [Finalize an order](https://studio.inttegro.com/machine/java/api/orders.md#finalize-an-order) - Seal the current order state without charging
- [Pay for an order](https://studio.inttegro.com/machine/java/api/orders.md#pay-for-an-order) - Start payment after the latest revision is ready
- [Order lifecycle](https://studio.inttegro.com/machine/java/guides/order-lifecycle.md) - Understand which statuses still allow updates
- [Order now, pay later](https://studio.inttegro.com/machine/java/guides/order-now-pay-later.md) - Build deferred payment flows around mutable orders