Skip to content
KasblyKasbly Docs

Create order

POST
/api/v1/orders
curl --request POST \
  --url https://api.dokanmazad.com/api/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "customerId": "cmoabcde000001ny11aabbcc0", "carId": 10482, "carDetails": { "makeEn": "BMW", "modelEn": "3 Series", "year": 2023, "price": 25000 }, "totalAmount": 25000, "currency": "USD" }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

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

Customer CUID

string
carId

Source car integer ID. When provided, the car images are snapshotted to R2 under orders/{orderNumber}/ for archival.

number
carDetails

Car details JSON snapshot (makeEn, modelEn, year, price, …). Also accepts the special key customerNotificationsEnabled documented as its own row below.

object
carDetails.customerNotificationsEnabled

Embed inside carDetails (e.g. { makeEn: "BMW", customerNotificationsEnabled: false }). When false, all WhatsApp notifications to the customer for THIS order are suppressed (staff notifications still fire). Default true.

boolean
marketerId

Marketer CUID. Auto-set if the authenticated user is a marketer.

string
tenantId

Tenant CUID. Auto-set from the authenticated user context.

string
totalAmount

Total order amount (minimum 0)

number
currency

ISO 4217 currency — USD | KRW | AED (default: USD)

string
notes

Internal notes visible to staff

string
receiptAmount

Payment receipt amount from customer (minimum 0)

number
receiptCurrency

Currency of the receipt

string
receiptDescription

Description or reference for the payment receipt (e.g. bank transfer ref)

string
receiptFileUrl

URL of uploaded receipt file (image or PDF)

string
useWalletBalance

When true, the order is paid entirely from the customer wallet balance and skips deposit/payment workflow steps — status starts at InspectionScheduled. PREREQUISITE: call GET /v1/wallets/:customerId first and confirm balance >= totalAmount. If balance is insufficient, the order creation will fail with code WALLET_INSUFFICIENT_BALANCE. Default: false.

boolean
inspectionDate

Inspection date — required when useWalletBalance=true (order bypasses deposit steps)

string format: date-time
Examples
Exampledefault
{
  "customerId": "cmoabcde000001ny11aabbcc0",
  "carId": 10482,
  "carDetails": {
    "makeEn": "BMW",
    "modelEn": "3 Series",
    "year": 2023,
    "price": 25000
  },
  "totalAmount": 25000,
  "currency": "USD"
}

Responses

Section titled “Responses”

201

Section titled “201”

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

Newly created order CUID

string
orderNumber
required

Sequential order number

number
status
required

DepositSubmitted on create (or InspectionScheduled when useWalletBalance=true)

string
allowedStatusTransitions
required

Valid next statuses from creation state

Array<string>
progress
required

Order progress (0 at creation)

number
canCancel
required

Whether order can be cancelled (true at creation)

boolean
isTerminal
required

Whether order is in terminal state (false at creation)

boolean
version
required

Starts at 1

number
createdAt
required

Creation timestamp

string format: date-time
Examples
Examplesuccess
{
  "success": true,
  "data": {
    "id": "cmosor2zy000313ny24hgtfy0",
    "orderNumber": 1042,
    "status": "DepositSubmitted",
    "allowedStatusTransitions": [
      "DepositConfirmed",
      "Cancelled"
    ],
    "progress": 0,
    "canCancel": true,
    "isTerminal": false,
    "version": 1,
    "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-01T08: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