Skip to main content

List Orders

Retrieve a list of orders with filtering and pagination.

Endpoint​

GET /v1/order/list

Request​

Header Parameters​

ParameterTypeRequiredExampleDescription
AuthorizationstringYesBearer YOUR_ACCESS_TOKENBearer access token used for authentication.
Content-TypestringYesapplication/jsonRequest body content type.

Query Parameters​

FieldTypeRequiredDefaultDescription
order_statusstringNoallFilter by order status
start_datestringNo-Filter orders created after this date (YYYY-MM-DD)
end_datestringNo-Filter orders created before this date (YYYY-MM-DD)
sort_keystringNocreate_timeSort field (order_id, create_time)
sort_dirstringNoDESCSort direction (ASC, DESC)
pageintegerNo1Page number for pagination
limitintegerNo20Items 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 CodeDescription
DRAFTDraft order (not submitted)
PENDING_CONFIRMOrder awaiting confirmation/payment
READY_TO_SHIPOrder confirmed and ready for pickup
PENDING_PICKUPWaiting for courier pickup
PICKUP_COMPLETEDPicked up by courier
IN_TRANSITPackage in transit
DELIVEREDPackage delivered
COMPLETEDOrder completed
CANCELLEDOrder cancelled
PROCESSINGOrder being processed.
Example: generating/printing shipping label.
PENDING_PROCESSINGOrder 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 (gross) weight of this parcel, 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"
total_act_weight
string
Total actual (gross) weight of all parcels, in kg.
Example: 0.5
total_vol_weight
string
Total volumetric weight of all parcels, in kg. Also called dimensional weight, based on parcel size (L × W × H).
Example: 1
total_count_weight
string
Total chargeable weight of all parcels, in kg. For each parcel, chargeable weight is the greater of actual weight and volumetric weight. This is the weight used to quote shipping.
Example: 1
final_count_weight
string
Final billed weight confirmed by the courier, in kg. Empty until the courier issues an invoice.
Example: 1
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"
            }
          ],
          "total_act_weight": "0.5",
          "total_vol_weight": "1",
          "total_count_weight": "1",
          "final_count_weight": "1"
        },
        "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"
  }
}