List Orders

Retrieve a list of orders with filtering and pagination.

Endpoint

GET /v1/order/list

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.

---

Query Parameters

Field	Type	Required	Default	Description
order_status	string	No	all	Filter by order status
start_date	string	No	-	Filter orders created after this date (YYYY-MM-DD)
end_date	string	No	-	Filter orders created before this date (YYYY-MM-DD)
sort_key	string	No	create_time	Sort field (order_id, create_time)
sort_dir	string	No	DESC	Sort direction (ASC, DESC)
page	integer	No	1	Page number for pagination
limit	integer	No	20	Items per page (max: 100)

Example request

curl -X GET "${API_URL}/v1/order/list?order_status=PENDING_CONFIRM&start_date=2025-01-01&end_date=2025-12-31&page=1&limit=20&sort_key=create_time&sort_dir=DESC" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json"

Responses

200 Success

200 Success

Response schema: application/json

data

json-string

List response wrapper.

Expand for fields.

order_list

json-string

Array of order objects.

Example: [{...}]

Expand for order fields.

order_id

string

Unique order identifier.

Example: 3550875

ship_type

string

Shipping type.

Example: local

order_status

string

Current order status code.

Example: READY_TO_SHIP

Expand for supported values.

Order status codes:

Status Code	Description
DRAFT	Draft order (not submitted)
PENDING_CONFIRM	Order awaiting confirmation/payment
READY_TO_SHIP	Order confirmed and ready for pickup
PENDING_PICKUP	Waiting for courier pickup
PICKUP_COMPLETED	Picked up by courier
IN_TRANSIT	Package in transit
DELIVERED	Package delivered
COMPLETED	Order completed
CANCELLED	Order cancelled
PROCESSING	Order being processed. Example: generating/printing shipping label.
PENDING_PROCESSING	Order requires manual handling by Fuuffy IT staff. Contact Fuuffy IT for follow-up.

quote_price

string

Quoted shipping price.

Example: 28.50

confirm_shipment

string

Whether order is confirmed (Y or N).

Example: Y

tracking_number

string | null

Tracking number when assigned.

Example: SF7444700508450

client_remarks

string | null

Client reference or remarks.

Example: #5493979

sender

json-string

Sender information.

Expand for fields.

name

string

Contact name.

Example: Fuuffy Chai

mobile

string

Phone number (without country code).

Example: 64105317

mobile_prefix

string

Country code.

Example: 852

email

string

Email address.

Example: cs@fuufy.com

address

string

Full formatted address.

Example: HONG KONG

recipient

json-string

Recipient information.

Expand for fields.

name

string

Contact name.

Example: 小編姐姐

mobile

string

Phone number (without country code).

Example: 64105317

mobile_prefix

string

Country code.

Example: 852

email

string

Email address.

Example: cs@fuuffy.com

address

string

Full formatted address.

Example: HONG KONG

shipment_detail

json-string

Shipment and parcel details.

Expand for fields.

package_type

string

Type of package.

Example: parcel

consignment_declaration

string

Contents declaration.

Example: Toys

parcel_list

json-string

Array of parcels in this shipment.

Expand for item fields.

act_weight

string

Actual weight in kg.

Example: "0.5"

length

string

Length in cm.

Example: "23"

width

string

Width in cm.

Example: "14"

height

string

Height in cm.

Example: "10"

insurance_fee

string

Insurance fee.

Example: "0"

parcel_items

json-string

Array of items in this parcel.

Expand for item fields.

name

string

Item name.

Example: Toy

qty

string

Quantity.

Example: "1"

single_value

string

Single item value in HKD.

Example: "200.00"

shipping_provider

string

Shipping provider code.

Example: sf_expresshk_local

create_time

string

Order creation timestamp (ISO 8601).

Example: 2025-12-09T17:01:30+08:00

pagination

json-string

Pagination information.

Expand for fields.

page

string

Current page number.

Example: 1

limit

string

Items per page.

Example: 20

total

string

Total number of orders.

Example: 515

message

string

Human-readable message.

Example: OK

Response sample

{
  "data": {
    "order_list": [
      {
        "order_id": "3550875",
        "ship_type": "local",
        "order_status": "READY_TO_SHIP",
        "quote_price": "28.50",
        "confirm_shipment": "Y",
        "tracking_number": "SF7444700508450",
        "client_remarks": "#5493979",
        "sender": {
          "name": "Fuuffy Chai",
          "mobile": "64105317",
          "mobile_prefix": "852",
          "email": "cs@fuufy.com",
          "address": "HONG KONG"
        },
        "recipient": {
          "name": "小編姐姐",
          "mobile": "64105317",
          "mobile_prefix": "852",
          "email": "cs@fuuffy.com",
          "address": "HONG KONG"
        },
        "shipment_detail": {
          "package_type": "parcel",
          "consignment_declaration": "Toys",
          "parcel_list": [
            {
              "act_weight": "0.5",
              "height": "10",
              "width": "14",
              "length": "23",
              "parcel_items": [
                { "name": "Toy", "qty": "1", "single_value": "200" }
              ],
              "insurance_fee": "0"
            }
          ]
        },
        "shipping_provider": "sf_expresshk_local",
        "create_time": "2025-12-09T17:01:30+08:00"
      }
    ],
    "pagination": { "page": "1", "limit": "20", "total": "515" },
    "message": "OK"
  }
}

400 Bad Request

400 Bad Request

Response schema: application/json

error.code

string

Error code.

Example: 400000

error.code_reason

string

Error reason.

Example: BAD_REQUEST

error.message

string

Human-readable message.

Example: Bad Request

error.error_trace

array

List of validation errors.

Expand for fields.

field

string

Request field that failed.

Example: limit

message

string

Human-readable message.

Example: limit must be an integer between 1 and 100

Response sample

{
  "error": {
    "code": "400000",
    "code_reason": "BAD_REQUEST",
    "message": "Bad Request",
    "error_trace": [
      {
        "field": "order_status",
        "message": "order_status must be one of: READY_TO_SHIP, PENDING_CONFIRM, PENDING_PICKUP, PICKUP_COMPLETED, IN_TRANSIT, DELIVERED, COMPLETED, CANCELLED, PROCESSING, PENDING_PROCESSING"
      }
    ]
  }
}

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

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

403 Forbidden

403 Forbidden

Response schema: application/json

error

json-string

Access forbidden for this resource.

404 Not Found

404 Not Found

Response schema: application/json

error

json-string

Resource or endpoint not found.

500 Failure

500 Failure

Response schema: application/json

code

string

Error code.

Example: 500999

code_reason

string

Error reason.

Example: API_ERROR

message

string

Human-readable message.

Example: Api Error, please contact customer service

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