Skip to main content
View as Markdown

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 for the three update flows most teams hit in production without losing payment context or order history.

Use MCP for supported order changes

An authenticated AI agent can read the order and update selected mutable fields after your confirmation. Payment configuration and execution are outside update_order; finalize_order seals a draft separately. Read the order again to verify the change.

MCP tools: get_order, update_order or finalize_order

Confirmed MCP actions require explicit form confirmation before Inttegro changes state.

Prerequisites

How the update operation behaves

Reach for 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 finalize. 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
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.update({
  orderId: "or_4Jv9wK2LmQ8rT6xP1nY5sC3dF7hB0uA",
  number: "ORDER-2025-041-REV1",
  lineItems: [
    {
      type: Inttegro.LineItemTypes.Product,
      product: {
        name: "Warehouse-picked sneaker",
        type: Inttegro.ProductTypes.Physical,
        quantity: 2,
        price: {
          currency: "ghs",
          value: 9500,
        },
      },
    },
    {
      type: Inttegro.LineItemTypes.Fee,
      fee: {
        label: "Delivery fee",
        amount: {
          currency: "ghs",
          value: 1500,
        },
      },
    },
  ],
})

After the update:

  • Inttegro replaces the previous line items completely.
  • lineItemGroup.total and payment.amount 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
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.update({
  orderId: "or_aR7mK4qP9dT2xW6nC1yV8sJ5bL0fH3u",
  customData: {
    channel: "ops_review",
    edited_by: "merx",
    priority: "high",
  },
})

After the update:

  • Inttegro replaces the top-level customData 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 finalize: 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
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.orders.update({
  orderId: "or_zT5mQ8wL2pR7vK1xN4cD9sF6hB3uJ0y",
  number: "QUOTE-2025-009-REV2",
  finalize: true,
  lineItems: [
    {
      type: Inttegro.LineItemTypes.Product,
      product: {
        name: "Annual support retainer",
        type: Inttegro.ProductTypes.Service,
        quantity: 1,
        price: {
          currency: "ghs",
          value: 120000,
        },
      },
    },
    {
      type: Inttegro.LineItemTypes.Fee,
      fee: {
        label: "Onboarding workshop",
        amount: {
          currency: "ghs",
          value: 15000,
        },
      },
    },
  ],
})

After the update:

  • Inttegro recalculates the order total and payment amount from the revised items.
  • sealedAt is refreshed because the order was sealed again.
  • invoice 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 finalize: false instead. Inttegro will reopen the sealed order and clear the active invoice until you seal it again with Finalize an order or another Update an order call.