Orders

5 endpointsEnglish only

Read an order

get/orders/{orderId}experimentalSession required

Responds 403 when the caller is not a member of the order's workshop and 404 when no such order exists.

Path parameters

Name	Type	Required	Constraints	Description
orderId	string	Yes	-	Order id

Responses

200Success

Field	Type	Required	Constraints	Description
order	Order	Yes	-	An order as returned to a member: title, customer name and notes are edited in place through this same shape, status changes are recorded in statusHistory.

Example

{
  "order": {
    "id": "order-1",
    "workshopId": "workshop-1",
    "title": "Oak dining table",
    "customerName": "Anna Kowalska",
    "notes": "Six chairs to match, deliver by the 20th.",
    "status": "in_progress",
    "createdAt": "2026-08-01T09:00:00.000Z",
    "lastActivityAt": "2026-08-10T14:30:00.000Z",
    "statusHistory": [
      {
        "status": "todo",
        "at": "2026-08-01T09:00:00.000Z"
      },
      {
        "status": "in_progress",
        "at": "2026-08-10T14:30:00.000Z"
      }
    ]
  }
}

401Not authenticated
No body.
403Forbidden
No body.
404Not found
No body.

Example request

curl -X GET 'https://mercastra.cloud/api/orders/<orderId>' \
  -H 'Cookie: session=<session cookie>'

Update an order's title, customer name or notes

patch/orders/{orderId}experimentalSession required

Updates any subset of title, customerName and notes; at least one is required, the body is strict and an unknown field is a 400. None of these three fields counts as order activity: lastActivityAt and statusHistory are untouched by this endpoint. Responds 403 when the caller is not a member of the order's workshop and 404 when no such order exists.

Path parameters

Name	Type	Required	Constraints	Description
orderId	string	Yes	-	Order id

Request body

Field	Type	Required	Constraints	Description
title	string	No	`minLength: 1maxLength: 250pattern: "^[^\\p{Cc}]* quot;`	-
customerName	string	No	`maxLength: 250pattern: "^[^\\p{Cc}]* quot;`	-
notes	string	No	`maxLength: 5000`	-

Example

{
  "notes": "Six chairs to match, deliver by the 20th."
}

Responses

200Success

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
workshopId	string	Yes	-	-
title	string	Yes	-	-
customerName	string	Yes	-	Blank when the order has no named customer
notes	string	Yes	-	-
status	OrderStatus	Yes	-	An order's stage, always one of these three values in this order: todo, in_progress, done.
createdAt	string	Yes	`format: "date-time"`	-
lastActivityAt	string	Yes	`format: "date-time"`	-
statusHistory	array of OrderStatusHistoryEntry	Yes	-	-

Example

{
  "id": "order-1",
  "workshopId": "workshop-1",
  "title": "Oak dining table",
  "customerName": "Anna Kowalska",
  "notes": "Six chairs to match, deliver by the 20th.",
  "status": "in_progress",
  "createdAt": "2026-08-01T09:00:00.000Z",
  "lastActivityAt": "2026-08-10T14:30:00.000Z",
  "statusHistory": [
    {
      "status": "todo",
      "at": "2026-08-01T09:00:00.000Z"
    },
    {
      "status": "in_progress",
      "at": "2026-08-10T14:30:00.000Z"
    }
  ]
}

400The request body does not match the schema
The shared validation error body, see Validation errors.
401Not authenticated
No body.
403Forbidden
No body.
404Not found
No body.

Example request

curl -X PATCH 'https://mercastra.cloud/api/orders/<orderId>' \
  -H 'Cookie: session=<session cookie>' \
  -H 'X-CSRF-Token: <csrf-token cookie value>' \
  -H 'Content-Type: application/json' \
  -d '{"notes":"Six chairs to match, deliver by the 20th."}'

Change an order's status

patch/orders/{orderId}/statusexperimentalSession required

Appends a statusHistory entry timestamped now and sets lastActivityAt to the same moment. Responds 403 when the caller is not a member of the order's workshop and 404 when no such order exists.

Path parameters

Name	Type	Required	Constraints	Description
orderId	string	Yes	-	Order id

Request body

Field	Type	Required	Constraints	Description
status	OrderStatus	Yes	-	An order's stage, always one of these three values in this order: todo, in_progress, done.

Example

{
  "status": "done"
}

Responses

200Success

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
workshopId	string	Yes	-	-
title	string	Yes	-	-
customerName	string	Yes	-	Blank when the order has no named customer
notes	string	Yes	-	-
status	OrderStatus	Yes	-	An order's stage, always one of these three values in this order: todo, in_progress, done.
createdAt	string	Yes	`format: "date-time"`	-
lastActivityAt	string	Yes	`format: "date-time"`	-
statusHistory	array of OrderStatusHistoryEntry	Yes	-	-

Example

{
  "id": "order-1",
  "workshopId": "workshop-1",
  "title": "Oak dining table",
  "customerName": "Anna Kowalska",
  "notes": "Six chairs to match, deliver by the 20th.",
  "status": "done",
  "createdAt": "2026-08-01T09:00:00.000Z",
  "lastActivityAt": "2026-08-10T14:30:00.000Z",
  "statusHistory": [
    {
      "status": "todo",
      "at": "2026-08-01T09:00:00.000Z"
    },
    {
      "status": "in_progress",
      "at": "2026-08-10T14:30:00.000Z"
    }
  ]
}

400The request body does not match the schema
The shared validation error body, see Validation errors.
401Not authenticated
No body.
403Forbidden
No body.
404Not found
No body.

Example request

curl -X PATCH 'https://mercastra.cloud/api/orders/<orderId>/status' \
  -H 'Cookie: session=<session cookie>' \
  -H 'X-CSRF-Token: <csrf-token cookie value>' \
  -H 'Content-Type: application/json' \
  -d '{"status":"done"}'

List a workshop's orders

get/workshops/{workshopId}/ordersexperimentalSession required

Returns every order belonging to the workshop. Responds 403 when the caller is not a member of the workshop; there is no 404 for an unknown workshop id, a non-member sees 403 either way.

Path parameters

Name	Type	Required	Constraints	Description
workshopId	string	Yes	-	Workshop id

Responses

200Success

Field	Type	Required	Constraints	Description
orders	array of Order	Yes	-	-

Example

{
  "orders": [
    {
      "id": "order-1",
      "workshopId": "workshop-1",
      "title": "Oak dining table",
      "customerName": "Anna Kowalska",
      "notes": "Six chairs to match, deliver by the 20th.",
      "status": "in_progress",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "lastActivityAt": "2026-08-10T14:30:00.000Z",
      "statusHistory": [
        {
          "status": "todo",
          "at": "2026-08-01T09:00:00.000Z"
        },
        {
          "status": "in_progress",
          "at": "2026-08-10T14:30:00.000Z"
        }
      ]
    }
  ]
}

401Not authenticated
No body.
403Forbidden
No body.

Example request

curl -X GET 'https://mercastra.cloud/api/workshops/<workshopId>/orders' \
  -H 'Cookie: session=<session cookie>'

Create an order in a workshop

post/workshops/{workshopId}/ordersexperimentalSession required

Creates a new order with status todo and an empty notes field. `customerName` defaults to an empty string when omitted, an order can have no named customer. Responds 403 when the caller is not a member of the workshop; there is no 404 for an unknown workshop id, a non-member sees 403 either way. The body is not strict, an unknown field is silently dropped rather than rejected.

Path parameters

Name	Type	Required	Constraints	Description
workshopId	string	Yes	-	Workshop id

Request body

Field	Type	Required	Constraints	Description
title	string	Yes	`minLength: 1maxLength: 250pattern: "^[^\\p{Cc}]* quot;`	-
customerName	string	No	`maxLength: 250pattern: "^[^\\p{Cc}]* quot;`	-

Example

{
  "title": "Oak dining table",
  "customerName": "Anna Kowalska"
}

Responses

201Created

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
workshopId	string	Yes	-	-
title	string	Yes	-	-
customerName	string	Yes	-	Blank when the order has no named customer
notes	string	Yes	-	-
status	OrderStatus	Yes	-	An order's stage, always one of these three values in this order: todo, in_progress, done.
createdAt	string	Yes	`format: "date-time"`	-
lastActivityAt	string	Yes	`format: "date-time"`	-
statusHistory	array of OrderStatusHistoryEntry	Yes	-	-

Example

{
  "id": "order-1",
  "workshopId": "workshop-1",
  "title": "Oak dining table",
  "customerName": "Anna Kowalska",
  "notes": "Six chairs to match, deliver by the 20th.",
  "status": "in_progress",
  "createdAt": "2026-08-01T09:00:00.000Z",
  "lastActivityAt": "2026-08-10T14:30:00.000Z",
  "statusHistory": [
    {
      "status": "todo",
      "at": "2026-08-01T09:00:00.000Z"
    },
    {
      "status": "in_progress",
      "at": "2026-08-10T14:30:00.000Z"
    }
  ]
}

400The request body does not match the schema
The shared validation error body, see Validation errors.
401Not authenticated
No body.
403Forbidden
No body.

Example request

curl -X POST 'https://mercastra.cloud/api/workshops/<workshopId>/orders' \
  -H 'Cookie: session=<session cookie>' \
  -H 'X-CSRF-Token: <csrf-token cookie value>' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Oak dining table","customerName":"Anna Kowalska"}'