Skip to main content
The Update Order endpoint lets you modify an existing order (project) in AgencyHandy — change its name, status, budget, timeline, assigned managers, and more — all from an external system or automation script. The endpoint also supports file attachments, which are appended to the order’s system folder.
Before using this endpoint, complete the Getting Started guide to obtain your API key and Company ID.
This endpoint uses Authorization: Bearer <token> (a signed-in member’s access token) rather than just the x-api-key header. Make sure your caller is authenticated as an approved member of the target company. Unauthorized callers receive a 403 PermissionError.

​
Prerequisites

  • ✅ A valid Bearer token for an approved workspace member
  • ✅ Company ID retrieved from GET {{URL}}/accounts/companies
  • ✅ The Order ID (Project ID, pid) of the order you want to update

​
Endpoint

PUT {{URL}}/orders?pid=<ORDER_ID>
Content-Type: multipart/form-data — use this even when no files are attached to satisfy the server’s multipart parser.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer <ACCESS_TOKEN> — the signed-in member’s access token.
companyidYesMongo ObjectId of the company the order belongs to.
clientidOptionalReal-time client socket ID. When supplied, notifications include it.

​
Query parameters

​
pid
string
required
The Order / Project ID to update. Pass this as a query string parameter.

​
Request body fields

​
name
string
Updates the order title. Minimum 2 characters.
​
status
string
New status for the order. Must be one of: Pending, Ongoing, Review, Completed, Cancelled.Allowed transitions:
  • Review can only follow Ongoing or another Review. Jumping from Pending directly to Review returns a 400 ValidationError.
  • Orders already Completed or Cancelled cannot be updated.
  • Clients cannot cancel an order that has moved past Pending.
​
budget
number
Total budget figure. Must be ≥ 0. Uses the order’s existing currency unless currency is also provided.
​
currency
string
Currency code for the budget. Examples: USD, CAD, EUR.
​
quantity
number
Number of units purchased for the package. Must be ≥ 1.
​
deadline
string
ISO 8601 date string for the order’s due date. Example: "2025-12-31T00:00:00.000Z".
​
kickoffDate
string
ISO 8601 date string for the project start date.
​
notes
string
Internal notes visible to your team.
​
brief
string
Client brief or project summary.
​
assignedProjectManagers
array
Complete list of project manager member IDs to assign to this order. New IDs are added to the team; removed IDs are deleted. Each ID must belong to a member with a projectManager role inside the same company.
​
markTasksAsDone
boolean
Required when status is Completed or Cancelled. When true, all tasks in the order are marked done after the status change. When false, tasks remain in their current state.
​
rejectRequestedTasks
boolean
Allowed only when status is Completed or Cancelled. When true, all outstanding client-requested tasks are rejected after the status update.
​
repeatCount
number
Required only for subscription orders when changing recurrence frequency. Pair with repeatDuration.
​
repeatDuration
string
Required alongside repeatCount for subscription orders. One of: day, week, month, year.
​
billingCycleCount
number
Optional limit on recurring billing cycles. Defaults to 0 (no limit).
​
billingCycleEvent
string
How each billing cycle is handled. One of: createOrderWithTask, noChange.
​
files
file
Zero or more file attachments. Files are appended to the order’s system folder; existing files are never overwritten. Use multipart/form-data encoding and attach each file under the files field.

​
Example request

curl --request PUT "https://api.agencyhandy.com/orders?pid=ORDER_ID_HERE" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "companyid: <COMPANY_ID>" \
  --form "name=Website Redesign" \
  --form "status=Review" \
  --form "budget=12000" \
  --form "currency=USD" \
  --form "quantity=1" \
  --form "assignedProjectManagers[]=PROJECT_MANAGER_ID" \
  --form "notes=Scope finalized with client." \
  --form "brief=Launch-ready design refresh."
Equivalent JSON payload (convert to multipart form entries when sending files): 
{
  "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."
}

​
Responses

HTTP StatusDescription
200 OKUpdate succeeded.
400 ValidationErrorInvalid order ID, blocked status transition, or malformed payload. Response includes fieldName when relevant.
403 PermissionErrorCaller is not an approved member, lacks the company role, the workspace subscription has expired, or a client attempted a forbidden cancel.
500 Internal Server ErrorUnhandled exception — check server logs.

​
Success response

{
  "message": "Project has been updated"
}

​
Business rules and side effects

  • Status transitions are restricted. Review can only follow Ongoing or another Review. Attempting Pending → Review returns 400 ValidationError.
  • Moving a status from Pending to Ongoing, Review, or Completed activates the order’s file folder so uploaded files become accessible to the project team.
  • Setting status to Completed or Cancelled requires markTasksAsDone to be explicitly set to true or false.
  • Status changes to Review, Completed, or Cancelled automatically trigger client notifications:
    • Review — notifies the client that review is needed.
    • Completed — sends the orderCompletion notification to the client.
    • Cancelled — sends the orderCancellation notification to the client.
  • Every successful update fires an ORDER.UPDATED webhook event with the updated order document and attachment metadata, if you have an active webhook subscribed to that event.