Create Order

Create a new order.

Endpoint

POST /v1/orders

Request

Header Parameters

---

Parameter	Type	Required	Example	Description
Authorization	string	Yes	Bearer YOUR_ACCESS_TOKEN	Bearer access token used for authentication.
Content-Type	string	Yes	application/json	Request body content type.

---

Request Body Schema

application/json

---

senderrequired

object

Sender information.

namerequired

string

Sender's full name.

Example: John Doe

phonerequired

string

Sender's phone number.

Must include country code (e.g. +1234567890).

Example: +1234567890

email

string

Sender's email address.

Valid email format.

Example: john@example.com

addressrequired

string

Sender's full address.

Example: 123 Main Street

city

string

Sender's city.

Example: New York

postal_code

string

Sender's postal code.

Example: 10001

country

string

Sender's country code.

ISO 3166-1 alpha-2 (e.g. US, HK).

Example: US

recipientrequired

object

Recipient information.

namerequired

string

Recipient's full name.

Example: Jane Smith

phonerequired

string

Recipient's phone number.

Must include country code.

Example: +0987654321

email

string

Recipient's email address.

Example: jane@example.com

addressrequired

string

Recipient's full address.

Example: 456 Oak Avenue

city

string

Recipient's city.

Example: Los Angeles

postal_code

string

Recipient's postal code.

Example: 90001

country

string

Recipient's country code.

ISO 3166-1 alpha-2 (e.g. US, HK).

Example: US

packagerequired

object

Package information.

weightrequired

number

Package weight in kg.

Greater than 0, less than 100 kg.

Example: 2.5

dimensions

object

Package dimensions in cm.

Expand for fields.

lengthrequired

number

Length in cm.

Greater than 0, less than 200 cm.

Example: 30

widthrequired

number

Width in cm.

Greater than 0, less than 200 cm.

Example: 20

heightrequired

number

Height in cm.

Greater than 0, less than 200 cm.

Example: 15

description

string

Package contents description.

Example: Electronics

value

number

Declared value in USD.

Example: 150.00

service_type

string

Service type.

Example: express

Expand for valid values.

Supported values:

Value	Description	Delivery Time
standard	Standard delivery	3–5 business days
express	Express delivery	1–2 business days
same_day	Same-day delivery	Within 24 hours

reference

string

Your internal reference number.

Example: ORDER-12345

notes

string

Special instructions.

Example: Handle with care

Example Request Body

{
  "sender": {
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "john@example.com",
    "address": "123 Main Street",
    "city": "New York",
    "postal_code": "10001",
    "country": "US"
  },
  "recipient": {
    "name": "Jane Smith",
    "phone": "+0987654321",
    "email": "jane@example.com",
    "address": "456 Oak Avenue",
    "city": "Los Angeles",
    "postal_code": "90001",
    "country": "US"
  },
  "package": {
    "weight": 2.5,
    "dimensions": {
      "length": 30,
      "width": 20,
      "height": 15
    },
    "description": "Electronics",
    "value": 150.00
  },
  "service_type": "express",
  "reference": "ORDER-12345",
  "notes": "Handle with care"
}

Responses

201 Created

201 Created

Response schema: application/json

id

string

Unique order identifier.

Example: order_1a2b3c4d5e6f

tracking_number

string

Tracking number for the order.

Example: FUF123456789

status

string

Order status.

One of: pending, picked_up, in_transit, delivered, cancelled.

Example: pending

sender

object

Sender details (echo of request).

recipient

object

Recipient details (echo of request).

package

object

Package details (echo of request).

service_type

string

Service type used.

reference

string

Client reference.

notes

string

Special instructions.

estimated_delivery

string

Estimated delivery timestamp (ISO 8601).

Example: 2024-01-18T17:00:00Z

created_at

string

Creation timestamp (ISO 8601).

Example: 2024-01-15T10:30:00Z

updated_at

string

Last update timestamp (ISO 8601).

Example: 2024-01-15T10:30:00Z

Response sample

{
  "id": "order_1a2b3c4d5e6f",
  "tracking_number": "FUF123456789",
  "status": "pending",
  "sender": {
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "john@example.com",
    "address": "123 Main Street",
    "city": "New York",
    "postal_code": "10001",
    "country": "US"
  },
  "recipient": {
    "name": "Jane Smith",
    "phone": "+0987654321",
    "email": "jane@example.com",
    "address": "456 Oak Avenue",
    "city": "Los Angeles",
    "postal_code": "90001",
    "country": "US"
  },
  "package": {
    "weight": 2.5,
    "dimensions": {
      "length": 30,
      "width": 20,
      "height": 15
    },
    "description": "Electronics",
    "value": 150.00
  },
  "service_type": "express",
  "reference": "ORDER-12345",
  "notes": "Handle with care",
  "estimated_delivery": "2024-01-18T17:00:00Z",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

400 Bad Request

400 Bad Request

Response schema: application/json

code

string

Error code.

Example: validation_error

message

string

Human-readable error summary.

Example: Invalid request parameters

details

array

List of validation errors (field and message per item).

field

string

Request field that failed.

Example: sender.phone

message

string

Human-readable explanation.

Example: Phone number is required

Response sample

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      { "field": "sender.phone", "message": "Phone number is required" },
      { "field": "package.weight", "message": "Weight must be greater than 0" }
    ]
  }
}

401 Unauthorized

401 Unauthorized

Response schema: application/json

code

string

Error code.

Example: 401000

code_reason

string

Error reason.

Example: UNAUTHORIZED

message

string

Human-readable message.

Example: Unauthorized

Response sample

{
  "error": {
    "code": "401000",
    "code_reason": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

403 Forbidden

403 Forbidden

Response schema: application/json

error

object

Access forbidden for this resource.

404 Not Found

404 Not Found

Response schema: application/json

error

object

Resource or endpoint not found.

500 Failure

500 Failure

Response schema: application/json

code

string

Error code.

Example: 500999

code_reason

string

Machine-readable error reason.

Example: API_ERROR

message

string

Human-readable message.

Example: Api Error, please contact customer service

Response sample

{
  "error": {
    "code": "500999",
    "code_reason": "API_ERROR",
    "message": "Api Error, please contact customer service"
  }
}

Validation Rules

• Phone numbers: Must include country code (e.g. +1234567890).
• Weight: Must be greater than 0 and less than 100 kg.
• Dimensions: Each dimension must be greater than 0 and less than 200 cm.
• Country codes: Must be valid ISO 3166-1 alpha-2 codes.
• Email: Must be a valid email format.

Idempotency

To prevent duplicate orders, include an Idempotency-Key header:

curl -X POST "${API_URL}/v1/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-12345" \
  -d '{ ... }'

Next Steps

• Get Order Details
• Track Order
• Update Order
• Cancel Order