# Update an Order ### Prerequisites Review the steps in the [Getting Started](/english/agencyhandy-user-guide-for-agency/api-integration-guide/getting-started.md) guide before updating an order. It walks through configuring your API token, and selecting the correct `companyid`, which are all required for the instructions below. ### Endpoint * **Method:** `PUT` * **Path:** `{{URL}}/orders` * **Query string:** `pid=` (required) * **Content-Type:** `multipart/form-data` (use this even when no files are attached to satisfy the `multer` parser) ### Authorization & Headers | Header | Required | Description | | --------------- | -------- | ----------------------------------------------------------------------------------- | | `Authorization` | Yes | Bearer token for the signed-in member. Processed by the `authorization` middleware. | | `companyid` | Yes | Mongo ObjectId of the company in which the order exists. Required by most services. | | `clientid` | Optional | Real-time client socket id. If supplied, notification payloads include it. | ### Query Parameters | Name | Type | Description | | ----- | ----------------- | -------------------------------------------- | | `pid` | string (ObjectId) | The order / project id that will be updated. | ### Request Body Schema | Field | Type | Notes | | ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | string (min 2) | Updates the project title. | | `deadline` | ISO date | Adjusts the internal due date. | | `budget` | number ≥ 0 | Total budget figure (matches original currency). | | `quantity` | number ≥ 1 | Number of units purchased for the package. | | `currency` | string | `USD`, `CAD`, `EUR` etc. | | `status` | enum | One of `Pending`, `Ongoing`, `Review`, `Completed`, `Cancelled`. Business rules listed below. | | `kickoffDate` | ISO date | Project start date. | | `notes` | string | Internal notes. | | `brief` | string | Client brief / summary. | | `assignedProjectManagers` | array | Complete list of project manager member ids. New ids are added to the team; removed ids are deleted from the team. Each id must belong to a `projectManager` role inside the same company. | | `repeatCount` | number | Required only for subscription orders when changing recurrence settings. | | `repeatDuration` | enum | One of `month`, `week`, `day`, `year`. Required alongside `repeatCount` for subscription orders. | | `billingCycleCount` | number | Optional recurring billing limit. Defaults to `0` (no limit). | | `billingCycleEvent` | enum | Either `createOrderWithTask` or `noChange`. | | `markTasksAsDone` | boolean | **Required** when `status` is `Completed` or `Cancelled`. When `true`, all project tasks are marked done after the status change. | | `rejectRequestedTasks` | boolean | Allowed only when `status` is `Completed` or `Cancelled`. When `true`, any client-requested tasks are rejected after the update. | #### File Uploads Attach zero or more files under the `files` field. Every upload is appended to the order's system folder and its byte size is added to the folder's `sizeInBytes`. When files are provided the handler: 1. Uploads each attachment through the standard order upload pipeline. 2. Accumulates the uploaded file sizes and increments the folder size atomically. 3. Leaves previously uploaded order files untouched. ### Example JSON Payload Use this structure when constructing the body (convert the fields to multipart form entries when including files): ```json { "name": "Website Redesign", "status": "Review", "budget": 12000, "currency": "USD", "quantity": 1, "assignedProjectManagers": ["{{PROJECT_MANAGER_ID}}"], "repeatCount": 3, "repeatDuration": "month", "billingCycleEvent": "createOrderWithTask", "notes": "Scope finalized with client.", "brief": "Launch-ready design refresh." } ``` ### Business Rules & Side Effects * Caller must be an approved member of the `companyid` (`userProjectList` check). Unauthorized members receive `403 PermissionError`. * Orders already marked `Cancelled` or `Completed` cannot be updated (`400 ValidationError`). * Members signed in as `client` cannot cancel an order once it has moved out of `Pending` (`403 PermissionError`). * Status transitions are restricted: `Review` can only follow `Ongoing` or another `Review`. Trying to jump from `Pending` → `Review` returns `400 ValidationError`. * Changing status from `Pending` to any of `Ongoing`, `Review`, or `Completed` marks the project's folder as live (`isLive: true`). * Setting `status` to `Completed` or `Cancelled` requires an explicit `markTasksAsDone` boolean. When `true`, every task in the order is closed; when `false`, tasks remain untouched. * `rejectRequestedTasks` may only be `true` when the order is transitioning to `Completed` or `Cancelled`. If enabled, all outstanding client-requested tasks are rejected after the update. * Moving `status` to `Review`, `Completed`, or `Cancelled` triggers notifications: * `Review`: notifies the client that a review is needed. * `Completed`: sends the `orderCompletion` notification to the client. * `Cancelled`: sends the `orderCancellation` notification to the client. * After every successful update, the system fires an `ORDER.UPDATED` webhook event whose payload includes the updated project document plus the current attachment metadata. ### Responses | HTTP Status | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `200 OK` | Update succeeded. Body: `{ "message": "Project has been updated" }`. | | `400 ValidationError` | Invalid project id, blocked status transition, or malformed payload. Response contains `fieldName` when relevant. | | `403 PermissionError` | Member is not approved, lacks the company role, subscription expired, or a client attempted a forbidden cancel action. | | `500 Internal Server Error` | Unhandled exceptions are forwarded to the error middleware and logged via Winston. | ### Example Request ```bash curl --request PUT "{{URL}}/orders?pid={{PROJECT_ID}}" \ --header "Authorization: Bearer {{ACCESS_TOKEN}}" \ --header "companyid: {{COMPANY_ID}}" \ --form "name=Website Redesign" \ --form "status=Review" \ --form "budget=12000" \ --form "assignedProjectManagers[]={{PROJECT_MANAGER_ID}}" \ --form "repeatCount=3" \ --form "repeatDuration=month" \ --form "files=@/path/to/creative-brief.pdf" ``` **Sample success response** ```json { "message": "Project has been updated" } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.agencyhandy.com/english/agencyhandy-user-guide-for-agency/api-integration-guide/update-an-order.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.