Update an Order

This endpoint performs a partial update on an existing order. Only the fields you send in the body are modified; everything else stays intact. It is not a full document replacement.

Typical uses:

Fix the shipping address before the order is shipped.
Update customer contact data (phone, email).
Add or remove tags and internal notes.
Save custom metafields for your integration.

Don't modify items or totals

Items, totals, taxes, and discounts are immutable after the order is created. To change products or quantities, use the returns and refunds flow, which preserves accounting traceability.

Endpoint

Partially updates an existing order

Required permission: orders:update

Editable vs. read-only fields

Field	Editable	Reason
`customerInfo`	Yes	Contact data can be corrected.
`deliveryInfo`	Yes	You can adjust method or add tracking.
`shippingAddress`	Yes	Only until the order ships.
`billingAddress`	Yes	Editable any time before invoicing.
`tags`	Yes	Internal classification.
`notes`	Yes	Operational notes.
`metafields`	Yes	Custom fields.
`_id`	No	Immutable identifier.
`externalId`	No	Public order number.
`orderCreated`	No	Creation date is audit data.
`channelId` / `channelType`	No	Order origin.
`items`	No	Use returns / refunds.
`subtotal`, `tax`, `total`	No	Recalculated automatically.
`orderStatus`	No	Use status transitions.

Partial update example

curl -X PUT https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer fn_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "shippingAddress": {
      "street": "Calle Insurgentes 456, Apt 3B",
      "city": "Mexico City",
      "state": "CDMX",
      "zipCode": "03100",
      "country": "MX"
    },
    "customerInfo": { "phone": "+525598765432" },
    "tags": ["phone", "vip", "address-fixed"],
    "notes": "Customer changed address by phone on 2026-04-11"
  }'

Response example

The response contains the full order with the changes applied:

{
  "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
  "externalId": "FEN-10042",
  "orderStatus": "accepted",
  "paymentStatus": "paid",
  "total": 1986.26,
  "shippingAddress": {
    "street": "Calle Insurgentes 456, Apt 3B",
    "city": "Mexico City",
    "state": "CDMX",
    "zipCode": "03100",
    "country": "MX"
  },
  "customerInfo": {
    "customerId": "65f3a1b2c4d5e6f7a8b9c0d2",
    "firstName": "Maria",
    "lastName": "Gonzalez",
    "email": "maria.gonzalez@example.com",
    "phone": "+525598765432"
  },
  "tags": ["phone", "vip", "address-fixed"],
  "notes": "Customer changed address by phone on 2026-04-11",
  "orderCreated": "2026-04-11T14:23:11.000Z",
  "updatedAt": "2026-04-11T15:02:44.000Z"
}

Tip

Sending tags replaces the entire array. To add tags without losing existing ones, first get the order and merge the tags on your client.

Errors

Code	Status	Description
`VALIDATION_ERROR`	400	You sent a read-only or malformed field.
`READ_ONLY_FIELD`	400	Attempted to modify `items`, `total`, `externalId`, or another immutable field.
`ORDER_NOT_FOUND`	404	No order with that ID exists in your tenant.
`INVALID_STATUS_FOR_UPDATE`	409	Order is in a status that doesn't allow edits (e.g. `delivered` or `cancelled`).
`INSUFFICIENT_PERMISSIONS`	403	The API key doesn't have the `orders:update` scope.
`INVALID_API_KEY`	401	The API key is invalid or revoked.

Next steps

Update an Order

This endpoint performs a partial update on an existing order. Only the fields you send in the body are modified; everything else stays intact. It is not a full document replacement.

Typical uses:

Fix the shipping address before the order is shipped.

Update customer contact data (phone, email).

Add or remove tags and internal notes.

Save custom metafields for your integration.

Don't modify items or totals

Items, totals, taxes, and discounts are immutable after the order is created. To change products or quantities, use the returns and refunds flow, which preserves accounting traceability.

Editable vs. read-only fields

Field

Editable

Reason

customerInfo

Yes

Contact data can be corrected.

deliveryInfo

Yes

You can adjust method or add tracking.

shippingAddress

Yes

Only until the order ships.

billingAddress

Yes

Editable any time before invoicing.

tags

Yes

Internal classification.

notes

Yes

Operational notes.

metafields

Yes

Custom fields.

_id

Immutable identifier.

externalId

Public order number.

orderCreated

Creation date is audit data.

channelId / channelType

Order origin.

items

Use returns / refunds.

subtotal, tax, total

Recalculated automatically.

orderStatus

Use status transitions.

Partial update example

curl -X PUT https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer fn_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "shippingAddress": {
      "street": "Calle Insurgentes 456, Apt 3B",
      "city": "Mexico City",
      "state": "CDMX",
      "zipCode": "03100",
      "country": "MX"
    },
    "customerInfo": { "phone": "+525598765432" },
    "tags": ["phone", "vip", "address-fixed"],
    "notes": "Customer changed address by phone on 2026-04-11"
  }'

Response example

The response contains the full order with the changes applied:

{
  "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
  "externalId": "FEN-10042",
  "orderStatus": "accepted",
  "paymentStatus": "paid",
  "total": 1986.26,
  "shippingAddress": {
    "street": "Calle Insurgentes 456, Apt 3B",
    "city": "Mexico City",
    "state": "CDMX",
    "zipCode": "03100",
    "country": "MX"
  },
  "customerInfo": {
    "customerId": "65f3a1b2c4d5e6f7a8b9c0d2",
    "firstName": "Maria",
    "lastName": "Gonzalez",
    "email": "maria.gonzalez@example.com",
    "phone": "+525598765432"
  },
  "tags": ["phone", "vip", "address-fixed"],
  "notes": "Customer changed address by phone on 2026-04-11",
  "orderCreated": "2026-04-11T14:23:11.000Z",
  "updatedAt": "2026-04-11T15:02:44.000Z"
}

Tip

Sending tags replaces the entire array. To add tags without losing existing ones, first get the order and merge the tags on your client.

Errors

Code

Status

Description

VALIDATION_ERROR

400

You sent a read-only or malformed field.

READ_ONLY_FIELD

400

Attempted to modify items, total, externalId, or another immutable field.

ORDER_NOT_FOUND

404

No order with that ID exists in your tenant.

INVALID_STATUS_FOR_UPDATE

409

Order is in a status that doesn't allow edits (e.g. delivered or cancelled).

INSUFFICIENT_PERMISSIONS

403

The API key doesn't have the orders:update scope.

INVALID_API_KEY

401

The API key is invalid or revoked.