Skip to content
KasblyKasbly Docs

Transition order status

PATCH
/api/v1/orders/{id}/status
curl --request PATCH \
  --url https://api.dokanmazad.com/api/v1/orders/cmosor2zy000313ny24hgtfy0/status \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "status": "DepositConfirmed", "version": 1, "notes": "Deposit verified via bank transfer" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Order CUID

Example
cmosor2zy000313ny24hgtfy0

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
status
required

Target status to transition to (must follow state machine rules)

string
version
required

Current version from order.version — throws 409 ConflictException on mismatch (minimum 1)

number
notes

Reason for the status change (stored in the immutable OrderLog audit entry)

string
inspectionDate

Inspection date — required when transitioning to InspectionScheduled (ISO 8601 or Date-parseable string)

string
Examples
Exampledefault
{
  "status": "DepositConfirmed",
  "version": 1,
  "notes": "Deposit verified via bank transfer"
}

Responses

Section titled “Responses”

200

Section titled “200”

Success

Media typeapplication/json
object
success
required
boolean
data
required
meta
object
page
integer
limit
integer
total
integer
totalPages
integer
data
required
object
id
required

Order CUID

string
status
required

New order status after transition

string
allowedStatusTransitions
required

Valid next statuses from the new state (role-aware)

Array<string>
progress
required

Updated progress percentage (0–100, -1 for cancelled)

number
canCancel
required

Whether the order can be cancelled from the new status

boolean
isTerminal
required

Whether the new status is terminal

boolean
version
required

Incremented version after transition

number
updatedAt
required

Updated timestamp

string format: date-time
Examples
Examplesuccess
{
  "success": true,
  "data": {
    "id": "cmosor2zy000313ny24hgtfy0",
    "orderNumber": 1042,
    "status": "DepositConfirmed",
    "allowedStatusTransitions": [
      "InspectionScheduled",
      "Cancelled"
    ],
    "progress": 7,
    "canCancel": true,
    "isTerminal": false,
    "version": 2,
    "customerId": "cmoabcde000001ny11aabbcc0",
    "marketerId": "cmoabcde000002ny22aabbcc0",
    "tenantId": "cmoabcde000003ny33aabbcc0",
    "carDetails": {
      "makeEn": "BMW",
      "modelEn": "3 Series",
      "year": 2023,
      "price": 25000
    },
    "totalAmount": 25000,
    "currency": "USD",
    "notes": null,
    "inspectionDate": null,
    "customer": {
      "id": "cmoabcde000001ny11aabbcc0",
      "name": "Ahmed Ali",
      "email": "ahmed@example.com"
    },
    "marketer": {
      "id": "cmoabcde000002ny22aabbcc0",
      "name": "Sales Rep",
      "email": "sales@example.com"
    },
    "createdAt": "2026-05-01T08:00:00.000Z",
    "updatedAt": "2026-05-02T08:00:00.000Z"
  }
}

401

Section titled “401”

Unauthorized — missing or invalid API key

Media typeapplication/json
object
success
required
boolean
error
required
string
statusCode
required
integer
Example
{
  "success": false
}

403

Section titled “403”

Forbidden — route not in this key’s allowedRoutes

Media typeapplication/json
object
success
required
boolean
error
required
string
statusCode
required
integer
Example
{
  "success": false
}

429

Section titled “429”

Rate limit exceeded

Media typeapplication/json
object
success
required
boolean
error
required
string
statusCode
required
integer
Example
{
  "success": false
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying