# updateOrder

mutation · in the family [Order](/reference/order/)

## What it does

Edit a customer order — change its details.

Edit a Order's mutable attributes. Requires the unrestricted capability + the record's CURRENT revision. The birth-fixed fields (organizationId, channel, orderType, logicalFacilityId, currency) are not editable — void and open a new Order.

## Careful

Edits take effect immediately and write a new revision; the old revision stays in history.

## Who may call it

Capability area: **Selling** — Ringing sales, serving customers and issuing invoices.

- Owner
- Manager
- Associate Manager
- Sales Associate
- Cashier
- An API key whose scope allows `api:updateOrder`

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | [ID](/types/#scalars) `ID!` | yes | The id of the record. |
| `revision` | [ID](/types/#scalars) `ID!` | yes | The revision id you read on the record; the change is refused if an edit landed in the meantime. |
| `input` | [EditOrderInput](/types/EditOrderInput/) `EditOrderInput!` | yes | No further notes. |

## Returns

[Order](/types/Order/) `Order!` — A selling Order — the cart IS the open state (no Cart construct); orderType selects the FSM profile; lines embed with captured prices in integer minor units; the tax slots are pipeline-written at place over the master data; ecom place reserves stock, POS place does not — a layaway place reserves BOTH channels for the term; a special_order place NEVER reserves (goods are not on-hand — arrival reserves the claim).

## Example request

```graphql
mutation ExampleUpdateOrder($id: ID!, $revision: ID!, $input: EditOrderInput!) {
  updateOrder(id: $id, revision: $revision, input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    organizationId
    channel
    orderType
    validUntil
    termEndsAt
    convertedOrderId
    sourceDocumentId
    reorderOfOrderId
    logicalFacilityId
    currency
    exemptionCertificateId
    paymentState
    fulfillmentState
    recognitionState
    taxJurisdictionId
    subtotalMinor
    discountTotalMinor
    taxTotalMinor
    totalMinor
    fulfillmentFeeMinor
    fulfillmentFeeTaxMinor
    tenderedNetMinor
    tipTotalMinor
    paymentIds
    refundIds
    disputeIds
    invoiceIds
    couponIds
    sourcingSagaId
    commissionAgentUserIds
    affiliateId
  }
}
```

Variables:

```json
{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "input": {
    "caption": "Blue jeans"
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

## Example response

```json
{
  "data": {
    "updateOrder": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "SO-EXMP-0000-000F",
      "type": "Order",
      "caption": "Blue jeans",
      "status": "open",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "organizationId": "01900000-0000-7000-8000-44b781470000",
      "channel": "pos",
      "orderType": "sale",
      "validUntil": "<valid until>",
      "termEndsAt": "2027-01-31T00:00:00.000Z",
      "convertedOrderId": "01900000-0000-7000-8000-b1563ac60000",
      "sourceDocumentId": "01900000-0000-7000-8000-8fd6a7c40000",
      "reorderOfOrderId": "01900000-0000-7000-8000-5533d5a60000",
      "logicalFacilityId": "01900000-0000-7000-8000-8026f71c0000",
      "currency": "USD",
      "exemptionCertificateId": "01900000-0000-7000-8000-6c082e160000",
      "paymentState": "<payment state>",
      "fulfillmentState": "<fulfillment state>",
      "recognitionState": "<recognition state>",
      "taxJurisdictionId": "01900000-0000-7000-8000-3a64e3820000",
      "subtotalMinor": 1,
      "discountTotalMinor": 1,
      "taxTotalMinor": 1,
      "totalMinor": 1,
      "fulfillmentFeeMinor": 1,
      "fulfillmentFeeTaxMinor": 1,
      "tenderedNetMinor": 1,
      "tipTotalMinor": 1,
      "paymentIds": [
        "01900000-0000-7000-8000-f1636a750000"
      ],
      "refundIds": [
        "01900000-0000-7000-8000-a5d2e2d30000"
      ],
      "disputeIds": [
        "01900000-0000-7000-8000-d72df27f0000"
      ],
      "invoiceIds": [
        "01900000-0000-7000-8000-0a4b14ba0000"
      ],
      "couponIds": [
        "01900000-0000-7000-8000-6a9b05ef0000"
      ],
      "sourcingSagaId": "01900000-0000-7000-8000-2dfe37aa0000",
      "commissionAgentUserIds": [
        "01900000-0000-7000-8000-7aaf99300000"
      ],
      "affiliateId": "01900000-0000-7000-8000-ab1bc9b90000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

## Errors this call can answer

- `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/))
- `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/))
- `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/))
- `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/))
- `NOT_FOUND/*` — That record could not be found. ([NOT_FOUND](/errors/NOT_FOUND/))
- `CONFLICT/*` — The record’s state, or a change made in the meantime, does not allow this; the codes are on the CONFLICT page. ([CONFLICT](/errors/CONFLICT/))
- `VALIDATION/VERSION_REQUIRED` — The request did not say which app version it came from. ([VALIDATION](/errors/VALIDATION/))

## Dry run

Add `dryRun: true` to the request envelope (`extensions.at`) to rehearse this call: every check runs, the write is rehearsed against the current records and nothing is stored; the answer is the refusal a real call would give, or the record it would create. Every response to a rehearsal carries `dryRun: true`, so a rehearsed record is never mistaken for a saved one.