Create an order

POST /tms-partner/api/v1/order

Usage and important notes

Send top-level moneyCollection on this request. Pricing and creation are independent. If it is absent or null, the recorded response cod becomes 0 even if the quote included COD. Negative COD produces INVALID_PRICE. Do not send the obsolete request field cod: it is not read. Compare the returned cod against your intended collection amount.

Provide sender and recipient names, international-format phones, and addresses. The source describes seller as the fallback when shipper is empty, buyer when consignee is empty, and returnContact defaulting to shipper. Each parcel needs weight/weightUnit, dimensions, type, and at least one item with a name and positive weight. measurementUnit defaults to the literal CENTIMET. Only payerType=CONSIGNEE or SELLER is accepted; other values produce PAYER_INVALID.

vas containing GTN/NTN/VTT may override the submitted receiveType. deliveryPostcode is required unless vas contains GTN or VTT; with GTN it is forced to null. Source names and sender/receiver service labels are retained rather than reinterpreted.

txId supports partner-side reconciliation/deduplication; the source does not establish server-enforced idempotency, a deduplication window, or safe repeat-create behavior. Retain the initial response and reconcile an ambiguous timeout before submitting another create. Do not assume a repeated txId prevents a duplicate shipment.

Response: save id for label creation, status lookup, and cancellation. Creation uses textual status=CONFIRMED and statusName; status lookup/webhooks use numeric codes. totalFees includes VAT after discounts and totalTax is VAT. estDeliveryTime.date is DD/MM/YYYY. partnerInfo uses snake_case keys inside an otherwise camelCase order response. Addresses are reduced to components and formattedAddress; no address-level id/code/geometry or component typeName/typeLabel is echoed.

Authentication headers

Request fields

Provide sender/recipient or documented seller/buyer fallback. Requiredness describes source business requirements, not guaranteed validation responses.

Example JSON body

Save as request.json. Replace every ${…} string and example ID with actual environment values before sending. cURL with --data @request.json does not interpolate variables inside JSON files. Identities are synthetic.

{
  "receiveType": "AT_HOME",
  "shipper": {
    "name": "Example Warehouse",
    "phone": "${SHIPPER_PHONE}",
    "type": "PARTNER_WAREHOUSE",
    "address": {
      "components": [
        {
          "name": "Example warehouse, Street A",
          "type": "OTHER",
          "level": 999
        },
        {
          "id": "5025963",
          "code": "120211",
          "name": "Voat Phnum",
          "type": "VILLAGE",
          "level": 3
        },
        {
          "id": "4059553",
          "code": "1202",
          "name": "Doun Penh",
          "type": "DISTRICT",
          "level": 2
        },
        {
          "id": "4025120",
          "code": "PNP",
          "name": "Phnom Penh",
          "type": "PROVINCE",
          "level": 1
        },
        {
          "type": "NATIONAL",
          "name": "Cambodia",
          "code": "KH",
          "level": 0
        }
      ]
    }
  },
  "consignee": {
    "name": "Example Recipient",
    "phone": "${CONSIGNEE_PHONE}",
    "address": {
      "components": [
        {
          "name": "Example recipient, Street B",
          "type": "OTHER",
          "level": 999
        },
        {
          "id": "5025109",
          "code": "010201",
          "name": "បន្ទាយនាង",
          "type": "VILLAGE",
          "level": 3
        },
        {
          "id": "4059452",
          "code": "0102",
          "name": "មង្គលបូរី",
          "type": "DISTRICT",
          "level": 2
        },
        {
          "id": "4025109",
          "code": "BAN",
          "name": "Banteay Meanchey",
          "type": "PROVINCE",
          "level": 1
        },
        {
          "type": "NATIONAL",
          "name": "Cambodia",
          "code": "KH",
          "level": 0
        }
      ]
    }
  },
  "parcel": {
    "weight": 100,
    "weightUnit": "GRAM",
    "length": 10,
    "width": 10,
    "height": 10,
    "measurementUnit": "CENTIMET",
    "type": "GOODS",
    "items": [
      {
        "name": "Example product",
        "type": "GOODS",
        "value": 50,
        "weight": 10,
        "quantity": 8
      }
    ]
  },
  "payerType": "CONSIGNEE",
  "service": "CCN",
  "vas": [
    "NTN",
    "VTT"
  ],
  "moneyCollection": 50,
  "invoice": "NONE",
  "reference": "EXAMPLE-REFERENCE-001",
  "txId": "00000000-0000-4000-8000-000000000001",
  "note": ""
}

cURL example

BASE_URL must include /tms-partner/api/v1. Load the token and partner code from your private environment; never paste secrets into documentation or AI prompts.

curl --request POST "${BASE_URL}/order" \
  --header "X-Api-Token: ${API_TOKEN}" \
  --header "X-Client-Source: ${PARTNER_CODE}" \
  --header "Accept-Language: en" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @request.json

Example response

{
  "id": "EXAMPLE-ORDER-001",
  "status": "CONFIRMED",
  "statusName": "Awaiting acceptance",
  "service": "CCN",
  "serviceName": "Express",
  "orderScope": "DOMESTIC",
  "shipper": {
    "name": "Example Warehouse",
    "address": {
      "components": [
        {
          "name": "Example warehouse, Street A",
          "type": "OTHER",
          "level": 999
        },
        {
          "id": "5025963",
          "code": "120211",
          "name": "Voat Phnum",
          "type": "VILLAGE",
          "level": 3
        },
        {
          "id": "4059553",
          "code": "1202",
          "name": "Doun Penh",
          "type": "DISTRICT",
          "level": 2
        },
        {
          "id": "4025120",
          "code": "PNP",
          "name": "Phnom Penh",
          "type": "PROVINCE",
          "level": 1
        },
        {
          "type": "NATIONAL",
          "name": "Cambodia",
          "code": "KH",
          "level": 0
        }
      ],
      "formattedAddress": "Example warehouse, Phnom Penh, Cambodia"
    }
  },
  "consignee": {
    "name": "Example Recipient",
    "phone": "${CONSIGNEE_PHONE}",
    "address": {
      "components": [
        {
          "name": "Example recipient, Street B",
          "type": "OTHER",
          "level": 999
        },
        {
          "id": "5025109",
          "code": "010201",
          "name": "បន្ទាយនាង",
          "type": "VILLAGE",
          "level": 3
        },
        {
          "id": "4059452",
          "code": "0102",
          "name": "មង្គលបូរី",
          "type": "DISTRICT",
          "level": 2
        },
        {
          "id": "4025109",
          "code": "BAN",
          "name": "Banteay Meanchey",
          "type": "PROVINCE",
          "level": 1
        },
        {
          "type": "NATIONAL",
          "name": "Cambodia",
          "code": "KH",
          "level": 0
        }
      ],
      "formattedAddress": "Example recipient, Banteay Meanchey, Cambodia"
    }
  },
  "parcel": {
    "weight": 100,
    "weightUnit": "GRAM",
    "length": 10,
    "width": 10,
    "height": 10,
    "measurementUnit": "CENTIMET",
    "type": "GOODS",
    "items": [
      {
        "name": "Example product",
        "type": "GOODS",
        "value": 50,
        "weight": 10,
        "quantity": 8
      }
    ]
  },
  "cod": 50,
  "totalFees": 1.75,
  "totalTax": 0.16,
  "originalPrice": 1.59,
  "detailedFees": {
    "currency": "USD",
    "serviceFee": [
      {
        "service": "CCN",
        "fee": 1.44,
        "feeAfterVat": 1.59,
        "vatPrice": 0.14
      }
    ]
  },
  "payerType": "CONSIGNEE",
  "vas": [
    "NTN",
    "VTT"
  ],
  "estDeliveryTime": {
    "days": 1.5,
    "date": "15/10/2026"
  },
  "createdAt": "2026-10-14T09:00:00+00:00",
  "txId": "00000000-0000-4000-8000-000000000001",
  "invoice": "NONE",
  "receiveType": "AT_HOME",
  "partnerInfo": {
    "id": 900001,
    "partner_code": "EXAMPLE-PARTNER",
    "partner_name": "Example Partner",
    "type": "PARTNER"
  }
}

Response fields

Address levels

COD persistence diagram

View source

flowchart TD
  A["product.moneyCollection in pricing"] --> B["Select COD service branch only"]
  B --> C["Create a separate order request"]
  C --> D{"Top-level moneyCollection supplied?"}
  D -->|Yes| E["Persist and compare response.cod"]
  D -->|Missing or null| F["Order records cod = 0"]

Error handling

See HTTP codes and source limitations. HTTP success does not prove COD, fees, or cancellation are correct; inspect the documented business fields. Do not assume create-order retries are safe.