Create Order

API Overview

Submits a single new parcel order to the WMG platform. The system validates the recipient and sender details, assigns a WMG tracking number, and routes the parcel to the appropriate carrier. Use this endpoint for real-time order creation from your fulfillment workflow.

Request Information

Method: POST
Path: /openapi/order/create-order
Authentication: Standard OpenAPI token (MD5-based)

Request Headers

Field	Description
Content-Type	application/json
x-auth-name	$API_NAME
x-auth-seed	$SEED (13-digit millisecond Unix timestamp)
x-auth-token	$TOKEN (MD5 hash)

Request Parameters

The request body is in JSON format and includes the following fields:

Parameter	Type	Required	Description
custom_tracking_num	string	Yes	Your internal order reference. Alphanumeric, `-`, and `_` only; max 32 characters
recipient_name	string	Yes	Recipient full name; max 64 characters
recipient_country	string	Yes	Recipient ISO 3166-1 alpha-2 country code (uppercase, length 2)
recipient_phone	string	Yes	Recipient phone number; digits only; max 24 characters
recipient_address	string	Yes	Recipient street address; max 512 characters
sender_country	string	Yes	Sender ISO 3166-1 alpha-2 country code (uppercase, length 2)
client_size	string	Yes	Parcel dimensions in `L,W,H` (centimetres), three comma-separated non-negative numbers, e.g. `30,20,10`; max 30 characters
client_weight	float	Yes	Parcel weight (range 0–9999); unit per your account settings
declared_value	float	Yes	Declared customs value; range 0–9999.99
declared_value_currency	string	Yes	Declared-value currency in ISO 4217 alpha-3 (length 3)
item	array	Yes	Array of item objects — see `item[]` table below
postal_code	string	Conditional	Recipient postal code. Required for every destination except `HK`. Non-digit characters are stripped before validation, then the length is checked per destination (SG = 5–6, MY = 4–5, KR = 4–5, JP = 5–7, all other destinations 3–10)
recipient_state	string	Conditional	Recipient state / province; required when `recipient_country = US`; max 60 characters
recipient_city	string	No	Recipient city; max 64 characters
recipient_email	string	No	Recipient email address; max 320 characters
sender_name	string	Conditional	Sender full name; required for pickup service types; max 64 characters
sender_phone	string	Conditional	Sender phone (digits only, max 24); required for pickup service types
sender_address	string	Conditional	Sender street address (max 512); required for pickup service types
sender_postal_code	string	Conditional	Sender postal code (3–10). For pickup service types it is required unless `sender_country = HK`; for non-pickup service types it is optional
sender_city	string	No	Sender city; max 64 characters
sender_email	string	No	Sender email address; max 320 characters
service_type	string	No	Service type code, length 3. Use the code assigned to your account; when omitted the order is handled as last mile only. Pickup service types also require the `sender_*` fields
service_code	string	No	Carrier routing service code, length 3. Required and must be a valid code when `recipient_country = US`; optional for `SG` but must be valid if sent; ignored for every other destination. Contact WMG for the codes enabled on your account
instruction	string	No	Delivery instructions; max 1024 characters
cash	float	No	Cash-on-delivery amount; 0–9999.99; requires `cash_currency`
cash_currency	string	No	COD currency ISO 4217 alpha-3; for `recipient_country = SG` must be `SGD`; requires `cash`
supplier_name	string	No	Supplier name; max 64 characters
supplier_gstn	string	No	Supplier GST registration number; max 64 characters
total_gst_amount	float	No	Total GST amount; 0–9999.99
gst_currency	string	No	GST currency ISO 4217 alpha-3
gst_paid	string	No	`Y` or `N`
incoterm_type	string	No	Incoterm code: `DDU` or `DDP`
locker_type	string	No	Parcel locker handling. `A` = the address is already a locker address; `B` = a normal address that should be converted to the nearest locker. Only `A` and `B` are accepted.
locker_station	object	Conditional	Required when `locker_type` is `A`. See the locker_station table below.

Each element of item[] must contain:

Field	Type	Required	Description
description	string	Yes	Item description; max 255 characters
unitPrice	float	Yes	Unit price; ≥ 0
quantity	number	Yes	Quantity; ≥ 0
weight	float	Yes	Item weight; ≥ 0
currency	string	Yes	ISO 4217 alpha-3 currency code (length 3)
totalValue	float	Yes	Item total value; ≥ 0
countryOfOrigin	string	No	ISO 3166-1 alpha-2 country code (length 2)
itemHSCode	string	No	Customs HS code; max 255 characters
productURL	string	No	Product page URL; max 500 characters

locker_station

Field	Type	Required	Description	Length
zipcode	string	Yes	Zipcode	<= 16 characters
station_name	string	Yes	Station Name	<= 64 characters
station_address	string	Yes	Station Address	<= 255 characters
address_detail	string	Yes	Address Detail	<= 255 characters
distance	float	Yes	Distance
station_code	string	Yes	Station Code	<= 10 characters

Request Body Example

json

{
  "custom_tracking_num": "ORDER-20260501-001",
  "recipient_name": "Jane Smith",
  "recipient_country": "SG",
  "recipient_phone": "6591234567",
  "recipient_address": "123 Orchard Road",
  "recipient_city": "Singapore",
  "recipient_email": "jane@example.com",
  "postal_code": "238858",
  "sender_country": "SG",
  "client_size": "30,20,10",
  "client_weight": 1.5,
  "declared_value": 99.99,
  "declared_value_currency": "SGD",
  "item": [
    {
      "description": "Electronics",
      "itemHSCode": "8471300000",
      "quantity": 1,
      "unitPrice": 99.99,
      "weight": 1.5,
      "currency": "SGD",
      "totalValue": 99.99
    }
  ]
}

Token Generation Example

The authentication token is computed from your credentials and seed only -- request parameters are not included.

seed  = "1746700000000"   (13-digit ms timestamp)
token = md5( strtolower(api_name) + api_key + seed )

Authentication

This endpoint uses Standard OpenAPI Authentication (MD5 token).

For complete authentication instructions and code examples, see Authentication Guide.

Response Information

The response is in JSON format.

Response Format

Field	Type	Description
code	integer	Result code. `0` = success, `1` = failure
message	string	Result description
data	object	Response payload

Success Response

Status Code: 200
Response Body:

json

{
  "code": 0,
  "message": "success",
  "data": {
    "custom_tracking_num": "C240719112805334a634B",
    "wmg_tracking_num": "WGC000000000233",
    "date_time": "2024-07-19T13:34:26+08:00",
    "status": "",
    "error": []
  }
}

Field	Type	Description
data.custom_tracking_num	string	Your submitted order reference
data.wmg_tracking_num	string	WMG-assigned tracking number
data.date_time	string	ISO 8601 timestamp when the order was created
data.status	string	Per-order status flag; empty string for an accepted real-time create
data.error	array	Per-order errors collected during processing; empty array on success

Error Response

Status Code: 200 (business logic error) or 4xx/5xx (system error)
Response Body:

json

{
  "code": 1,
  "message": "Client Size invalid",
  "data": []
}

Common errors:

Authentication failure → code 1; the message depends on the cause (e.g. x-auth-token: INVALID, x-auth-seed: TIMEOUT) — see signature.md
Missing or invalid field -- code 1, field validation message (e.g. client_weight require, recipient_country invalid)
Duplicate custom_tracking_num for this client -- code 1, message custom_tracking_num (XXX) already exist
Invalid service_code -- code 1, message Service code invalid (US) or Service code (XXX) invalid (SG)
Recipient country not in the allowed list -- code 1, message recipient_country(XX) not allow
Per-item validation failure -- code 1, message Item <row> <field> <reason> (e.g. Item 1 unitPrice require)

Code Reference

Code	Description
0	Success
1	Failure

Example

Bash

bash

API_NAME="your_api_name"
API_KEY="your_api_key"
SEED=$(date +%s%3N)
TOKEN=$(printf '%s' "$(echo -n "$API_NAME" | tr '[:upper:]' '[:lower:]')${API_KEY}${SEED}" | md5sum | cut -d' ' -f1)

curl -X POST "https://api.test.wmgdelivery.com/v1/openapi/order/create-order" \
  -H "Content-Type: application/json" \
  -H "x-auth-name: $API_NAME" \
  -H "x-auth-seed: $SEED" \
  -H "x-auth-token: $TOKEN" \
  -d '{
    "custom_tracking_num": "ORDER-20260501-001",
    "recipient_name": "Jane Smith",
    "recipient_country": "SG",
    "recipient_phone": "6591234567",
    "recipient_address": "123 Orchard Road",
    "recipient_city": "Singapore",
    "recipient_email": "jane@example.com",
    "postal_code": "238858",
    "sender_country": "SG",
    "client_size": "30,20,10",
    "client_weight": 1.5,
    "declared_value": 99.99,
    "declared_value_currency": "SGD",
    "item": [{"description": "Electronics", "itemHSCode": "8471300000", "quantity": 1, "unitPrice": 99.99, "weight": 1.5, "currency": "SGD", "totalValue": 99.99}]
  }'

Windows PowerShell

powershell

$API_NAME = "your_api_name"
$API_KEY  = "your_api_key"
$SEED     = [string]([DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds())

$raw   = [System.Text.Encoding]::UTF8.GetBytes($API_NAME.ToLower() + $API_KEY + $SEED)
$md5   = [System.Security.Cryptography.MD5]::Create().ComputeHash($raw)
$TOKEN = -join ($md5 | ForEach-Object { $_.ToString("x2") })

$body = [ordered]@{
    custom_tracking_num     = "ORDER-20260501-001"
    recipient_name          = "Jane Smith"
    recipient_country       = "SG"
    recipient_phone         = "6591234567"
    recipient_address       = "123 Orchard Road"
    recipient_city          = "Singapore"
    recipient_email         = "jane@example.com"
    postal_code             = "238858"
    sender_country          = "SG"
    client_size             = "30,20,10"
    client_weight           = 1.5
    declared_value          = 99.99
    declared_value_currency = "SGD"
    item                    = @(@{ description = "Electronics"; itemHSCode = "8471300000"; quantity = 1; unitPrice = 99.99; weight = 1.5; currency = "SGD"; totalValue = 99.99 })
} | ConvertTo-Json -Depth 5 -Compress

$headers = @{
    "Content-Type" = "application/json"
    "x-auth-name"  = $API_NAME
    "x-auth-seed"  = $SEED
    "x-auth-token" = $TOKEN
}

$response = Invoke-RestMethod `
    -Uri "https://api.test.wmgdelivery.com/v1/openapi/order/create-order" `
    -Method Post -Headers $headers -Body $body
$response | ConvertTo-Json -Depth 10

Python

python

import hashlib, time
import requests

API_NAME = 'your_api_name'
API_KEY  = 'your_api_key'
SEED     = str(int(time.time() * 1000))
TOKEN    = hashlib.md5((API_NAME.lower() + API_KEY + SEED).encode()).hexdigest()

headers = {
    'Content-Type': 'application/json',
    'x-auth-name':  API_NAME,
    'x-auth-seed':  SEED,
    'x-auth-token': TOKEN,
}

body = {
    'custom_tracking_num':     'ORDER-20260501-001',
    'recipient_name':          'Jane Smith',
    'recipient_country':       'SG',
    'recipient_phone':         '6591234567',
    'recipient_address':       '123 Orchard Road',
    'recipient_city':          'Singapore',
    'recipient_email':         'jane@example.com',
    'postal_code':             '238858',
    'sender_country':          'SG',
    'client_size':             '30,20,10',
    'client_weight':           1.5,
    'declared_value':          99.99,
    'declared_value_currency': 'SGD',
    'item': [{'description': 'Electronics', 'itemHSCode': '8471300000', 'quantity': 1, 'unitPrice': 99.99, 'weight': 1.5, 'currency': 'SGD', 'totalValue': 99.99}],
}

resp = requests.post('https://api.test.wmgdelivery.com/v1/openapi/order/create-order', json=body, headers=headers)
print(resp.json())

Node.js / TypeScript

typescript

import crypto from 'node:crypto';

const API_NAME = 'your_api_name';
const API_KEY  = 'your_api_key';
const SEED     = String(Date.now());
const TOKEN    = crypto.createHash('md5').update(API_NAME.toLowerCase() + API_KEY + SEED).digest('hex');

const body = JSON.stringify({
    custom_tracking_num:     'ORDER-20260501-001',
    recipient_name:          'Jane Smith',
    recipient_country:       'SG',
    recipient_phone:         '6591234567',
    recipient_address:       '123 Orchard Road',
    recipient_city:          'Singapore',
    recipient_email:         'jane@example.com',
    postal_code:             '238858',
    sender_country:          'SG',
    client_size:             '30,20,10',
    client_weight:           1.5,
    declared_value:          99.99,
    declared_value_currency: 'SGD',
    item: [{ description: 'Electronics', itemHSCode: '8471300000', quantity: 1, unitPrice: 99.99, weight: 1.5, currency: 'SGD', totalValue: 99.99 }],
});

const resp = await fetch('https://api.test.wmgdelivery.com/v1/openapi/order/create-order', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-auth-name':  API_NAME,
        'x-auth-seed':  SEED,
        'x-auth-token': TOKEN,
    },
    body,
});
console.log(JSON.stringify(await resp.json(), null, 2));

PHP

php

<?php
$API_NAME = 'your_api_name';
$API_KEY  = 'your_api_key';
$SEED     = (string)(time() * 1000);
$TOKEN    = md5(strtolower($API_NAME) . $API_KEY . $SEED);

$body = [
    'custom_tracking_num'     => 'ORDER-20260501-001',
    'recipient_name'          => 'Jane Smith',
    'recipient_country'       => 'SG',
    'recipient_phone'         => '6591234567',
    'recipient_address'       => '123 Orchard Road',
    'recipient_city'          => 'Singapore',
    'recipient_email'         => 'jane@example.com',
    'postal_code'             => '238858',
    'sender_country'          => 'SG',
    'client_size'             => '30,20,10',
    'client_weight'           => 1.5,
    'declared_value'          => 99.99,
    'declared_value_currency' => 'SGD',
    'item'                    => [
        ['description' => 'Electronics', 'itemHSCode' => '8471300000', 'quantity' => 1, 'unitPrice' => 99.99, 'weight' => 1.5, 'currency' => 'SGD', 'totalValue' => 99.99],
    ],
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.test.wmgdelivery.com/v1/openapi/order/create-order');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'x-auth-name: '  . $API_NAME,
    'x-auth-seed: '  . $SEED,
    'x-auth-token: ' . $TOKEN,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);
$response = curl_exec($ch);
curl_close($ch);
echo json_encode(json_decode($response, true), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n";
?>

Notes

custom_tracking_num accepts only alphanumeric characters, -, and _; maximum 32 characters.
postal_code should contain digits only.
The authentication token does not include request parameters; only credentials and seed are used.
The seed must be a 13-digit millisecond Unix timestamp and within ±10 minutes of server time.
All parameters are case-sensitive.

Error Codes

code	message	Description
`1`	Authentication error message	Authentication failed; the returned message depends on the cause — see the full list in signature.md
`1`	`custom_tracking_num (XXX) already exist`	A previous order with the same `custom_tracking_num` already exists for this client. Note that `exist` has no trailing `s`
`1`	`Service code invalid`	`recipient_country = US` and `service_code` is missing or is not a recognised code
`1`	`Service code (XXX) invalid`	`recipient_country = SG` and the submitted `service_code` is not a recognised code
`1`	`recipient_country(XX) not allow`	The recipient ISO country code is not in the platform's allowed-country list
`1`	`Item <row> <field> <reason>`	One of the `item[]` rows failed validation; the row number and field name pinpoint the failure
`1`	Field validation message	Other field-level validation failures (required, length, format, enum)

Create Order ​

API Overview ​

Request Information ​

Request Headers ​

Request Parameters ​

Request Body Example ​

Token Generation Example ​

Authentication ​

Response Information ​

Response Format ​

Success Response ​

Error Response ​

Code Reference ​

Example ​

Bash ​

Windows PowerShell ​

Python ​

Node.js / TypeScript ​

PHP ​

Notes ​

Error Codes ​

Create Order

API Overview

Request Information

Request Headers

Request Parameters

Request Body Example

Token Generation Example

Authentication

Response Information

Response Format

Success Response

Error Response

Code Reference

Example

Bash

Windows PowerShell

Python

Node.js / TypeScript

PHP

Notes

Error Codes