Update an Order

This article covers three distinct endpoints for modifying an existing order:

PUT /orders/:orderId — partial update of the order.
PUT /orders/:orderId/customer — updates only the customer data.
POST /orders/:orderId/comments — adds a comment to the order's history.

Update an order

Partially updates an existing order

orderIdstringrequired

Order ID (24-character MongoDB ObjectId).

bodyobjectrequired

Partial order object — only send the properties you want to change.

{
  "shippingAddress": {
    "street": "Calle Insurgentes 456, Depto 3B",
    "city": "Ciudad de México",
    "state": "CDMX",
    "zipCode": "03100",
    "country": "MX"
  },
  "notes": "Cliente cambió dirección por teléfono el 11-abr-2026"
}

200

{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "orderStatus": "accepted",
    "shippingAddress": {
      "street": "Calle Insurgentes 456, Depto 3B",
      "city": "Ciudad de México",
      "state": "CDMX",
      "zipCode": "03100",
      "country": "MX"
    },
    "notes": "Cliente cambió dirección por teléfono el 11-abr-2026",
    "updatedAt": "2026-04-11T15:02:44.000Z",
    "_links": {
      "self": "/orders/65f3a1b2c4d5e6f7a8b9c0d1",
      "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
      "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
    }
  }
}

404

{ "error": { "code": "orders:not_found", "message": "Order not found" } }

Required permission: orders:update

The request body accepts a partial order object (Partial<Order>): you send only the properties you want to change and the rest of the document stays intact.

Use the dedicated endpoints to change status

This endpoint is not designed to advance the order's lifecycle. For that, use the state transition endpoints (/accept, /reject, /cancel, /status, /transition), which apply the state machine's business rules and get logged in the audit trail. Sending orderStatus (or other computed fields like items, subtotal, tax, or total) directly through this endpoint bypasses that business validation — avoid doing so, even though the transport layer doesn't explicitly reject it.

Example

curl -X PUT https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer fkapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "shippingAddress": {
      "street": "Calle Insurgentes 456, Depto 3B",
      "city": "Ciudad de México",
      "state": "CDMX",
      "zipCode": "03100",
      "country": "MX"
    },
    "notes": "Cliente cambió dirección por teléfono el 11-abr-2026"
  }'

Example response

{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "orderStatus": "accepted",
    "shippingAddress": {
      "street": "Calle Insurgentes 456, Depto 3B",
      "city": "Ciudad de México",
      "state": "CDMX",
      "zipCode": "03100",
      "country": "MX"
    },
    "notes": "Cliente cambió dirección por teléfono el 11-abr-2026",
    "updatedAt": "2026-04-11T15:02:44.000Z",
    "_links": {
      "self": "/orders/65f3a1b2c4d5e6f7a8b9c0d1",
      "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
      "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
    }
  }
}

Update only the customer data

Dedicated endpoint to replace only the order's customer information, without touching the rest of the document.

Updates the customer data associated with the order

orderIdstringrequired

Order ID.

namestringrequired

Customer name.

{ "name": "María González Reyes" }

200

{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "customerInfo": { "name": "María González Reyes" },
    "updatedAt": "2026-04-11T15:05:10.000Z",
    "_links": { "self": "/orders/65f3a1b2c4d5e6f7a8b9c0d1" }
  }
}

404

{ "error": { "code": "orders:not_found", "message": "Order not found" } }

Required permission: orders:update

The body accepts the same customerInfo object used when creating an order: the only field confirmed as required is name.

curl -X PUT https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1/customer \
  -H "Authorization: Bearer fkapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "María González Reyes" }'

Example response

{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "customerInfo": { "name": "María González Reyes" },
    "updatedAt": "2026-04-11T15:05:10.000Z",
    "_links": {
      "self": "/orders/65f3a1b2c4d5e6f7a8b9c0d1"
    }
  }
}

Add a comment

Adds a note to the order's history. Unlike notes (a replaceable free-text field via PUT /orders/:orderId), a comment is recorded as an append-only event.

Adds a comment to the order

orderIdstringrequired

Order ID.

commentstringrequired

Comment text.

{ "comment": "Cliente confirmó recepción vía WhatsApp" }

200

{ "data": { "success": true, "orderId": "65f3a1b2c4d5e6f7a8b9c0d1" } }

404

{ "error": { "code": "orders:not_found", "message": "Order not found" } }

Required permission: orders:update

curl -X POST https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1/comments \
  -H "Authorization: Bearer fkapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "comment": "Cliente confirmó recepción vía WhatsApp" }'

Example response

{
  "data": {
    "success": true,
    "orderId": "65f3a1b2c4d5e6f7a8b9c0d1"
  }
}

Tip

See the full history of comments and events with GET /orders/:orderId/activity-log.

Errors

Code	Status	Description
`orders:not_found`	404	No order exists with that ID in your tenant.
`validation:invalid_input`	400	The body doesn't match the expected format (for example, missing `comment` or `name`).
`auth:invalid_token`	401	The API key is invalid or has been revoked.
`auth:permission_denied`	403	The API key doesn't have the `orders:update` scope.

See the full error catalog for the rest of the domain's codes.