NAV
json

Introduction

Welcome to the Boxful Fulfillment API! You can use our API to access Boxful Fulfillment API endpoints, which can manage your orders, storage in Boxful Fulfillment system.

Production: https://www.boxful.com/fulfillment/open-api/
Development: https://sandbox.boxful.com/fulfillment/open-api/

Authentication

Boxful Fulfillment uses API keys to allow access to the API. You can request a Boxful Fulfillment API key through email fulfillment@boxful.com.

Boxful Fulfillment expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Your_API_Key_Here
User-Agent: Your_Handle

Version 2020-11

Logistics

Get Logistics Information.

Get Logistics Method

Response:

{
"status": 200,
"message": "",
"data": [
{
"logistics": "own-self",
"logistics_code_id": 0,
"description": "自行出貨"
},
{
"logistics": "boxful",
"logistics_code_id": 1,
"description": "Boxful"
}
]
}

Get Logistics method that are enabled to your OMS account.

HTTP Request

GET /2020-11/logistics

Response Schema:

Key Type Description
logistics string The name of the logistic.
logistics_code_id integer The logistic ID.
description string Description of the logistics.

Order

Manage your outbound orders.

Add An Outbound Order

Response:

{
"status": 200,
"message": "",
"data": 1024,
}

Add a new outbound order.

HTTP Request

POST /2020-11/orders

Body Parameters

Parameter Description Required
custom_order_id Your own custom order ID for reference. Y
recipient_name Recipient’s name. Y
recipient_phone Recipient’s phone number. Y
recipient_email Recipient’s email. Y
recipient_address Recipient’s address. Y
logistic Refer to logistic_code_id which get from GET /2020-11/logistics Y
instruction Instruction of the order.
collection_amount The amount of cash collecting on delivery.
goods[][“sku”] Product SKU. Y
goods[][“retrieving_type”] Retrieving type - pallet_out, item_out, piece_out Y
goods[][“count”] Product quantity Y

Response Schema:

Type Description
integer Order ID of OMS.

Update An Order

Response:

{
"status": 200,
"message": "",
"data": 1024,
}

Update an order’s information including Recipient’s name, phone or address.

HTTP Request

PATCH /2020-11/orders

Body Parameters

Parameter Description Required
order_id Order ID of Boxful Fulfillment System. *Remarks 1
custom_order_id User defined Custom Order ID. *Remarks 1
recipient_name Recipient’s name.
recipient_phone Recipient’s phone number.
recipient_address Recipient’s address.

*Remarks 1: Please give either one of above for searching.

Response Schema:

Type Description
integer Order ID of OMS.

Get A Specific Order

Response:

{
"status": 200,
"message": "",
"data": {
"packing_list_main_id": "",
"logistics_date": "2020-10-19",
"type": "shipment",
"type_label": "出倉",
"address": "299 Queen's Road Central, Sheung Wan, Hong Kong, Central, Hong Kong Island",
"name": "hing test",
"phone": "123456789",
"instruction": "outbound",
"remark": null,
"2b_schedule_id": "1001",
"collect_amount": 0,
"vendor_order_id": null,
"wms_order_id": "16027468825056101517",
"status": "shipment",
"package_box": [
{
"package_id": 97,
"label": "test",
"length": 10,
"width": 10,
"height": 10,
"weight": 0,
"count": 20
},
{
"package_id": 98,
"label": "test",
"length": 10,
"width": 10,
"height": 10,
"weight": 0,
"count": 20
}
],
"item_list": [
{
"id": 114,
"parent_id": null,
"item_name": "Bundle Item A",
"item_sku": "SKU Bundle Item A",
"item_barcode": "15922790199856485692",
"item_qty": 20,
"item_expiry_date": "2020-06-19",
"retrieving_type": "bundle_out",
"retrieving_type_label": "商品組合",
"serial_number": []
},
{
"id": 115,
"parent_id": null,
"item_name": "Item 2",
"item_sku": "SKU2",
"item_barcode": "12345",
"item_qty": 20,
"item_expiry_date": "2020-06-19",
"retrieving_type": "piece_out",
"retrieving_type_label": "揀貨出倉",
"serial_number": []
}
],
"item_list_tree": [
{
"id": 114,
"parent_id": null,
"item_name": "Bundle Item A",
"item_sku": "SKU Bundle Item A",
"item_barcode": "15922790199856485692",
"item_qty": 20,
"item_expiry_date": "2020-06-19",
"retrieving_type": "bundle_out",
"retrieving_type_label": "商品組合",
"serial_number": [],
"children": [
{
"id": 116,
"parent_id": 114,
"item_name": "Item A",
"item_sku": "SKUA",
"item_barcode": "4718201718742",
"item_qty": 20,
"item_expiry_date": null,
"retrieving_type": "piece_out",
"retrieving_type_label": "揀貨出倉",
"serial_number": []
},
{
"id": 117,
"parent_id": 114,
"item_name": "Item B",
"item_sku": "SKUB",
"item_barcode": "4718201718743",
"item_qty": 20,
"item_expiry_date": null,
"retrieving_type": "piece_out",
"retrieving_type_label": "揀貨出倉",
"serial_number": []
}
]
},
{
"id": 115,
"parent_id": null,
"item_name": "商品2",
"item_sku": "SKU2",
"item_barcode": "12345",
"item_qty": 20,
"item_expiry_date": "2020-06-19",
"retrieving_type": "piece_out",
"retrieving_type_label": "揀貨出倉",
"serial_number": []
}
],
"logistics": [
{
"logistics_vendor": "boxful",
"logistics": "boxful",
"logistics_status": "shipment",
"service_at": null,
"logistics_status_label": "已出貨",
"logistics_code": "A244AE26569SG",
"logistics_log": [],
"logistics_image": []
},
{
"logistics_vendor": "boxful",
"logistics": "boxful",
"logistics_status": "shipment",
"service_at": null,
"logistics_status_label": "已出貨",
"logistics_code": "E45AE26569SGA",
"logistics_log": [],
"logistics_image": []
}
]
}
}

Get a specific order by using Order ID / Custom Order Id.

HTTP Request

GET /2020-11/orders/

Example:
GET /2020-11/orders/?order_id=1001

URL Parameters

Parameter Description Required
order_id Order ID of Boxful Fulfillment System. *Remarks 1
custom_order_id User defined Custom Order ID. *Remarks 1

*Remarks 1: Please give either one of above for searching.

Response Schema:

Key Type Description
packing_list_main_id integer Packing list ID which only appears at inbound order.
logistics_date string The outbound date.
type string The logistics type.
type_label string The name of logistics type.
address string Recipient’s address.
name string Recipient’s name.
phone string Recipient’s phone number.
instruction string The order’s instruction.
remarks string The order’s remarks which added by boxful.
2b_schedule_id integer The order ID of boxful fulfillment OMS.
collect_amount integer The amount of cash collecting on delivery.
vendor_order_id string The custom order id which defined by customer itself.
wms_order_id string The order id from Boxful WMS.
status string The status of the order.
package_box array Array of package boxes contain information of package box.
item_list array Array of product list related to the order.
item_list[][id] integer The ID of the product.
item_list[][parent_id] integer The parent ID of the product. Only applys to bundle.
item_list[][item_name] string The name of the product.
item_list[][item_sku] string The SKU of the product.
item_list[][item_barcode] string The Barcode of the product.
item_list[][item_qty] integer The total quantity of the product.
item_list[][item_expiry_date] string The expiry date of the product.
item_list[][retrieving_type] string The outbound type: item_out, pallet_out, piece_out, bundle_out.
item_list[][retrieving_type_label] string The name of the outbound type.
item_list[][serial_number] array Array of serial number.
item_list_tree array Array of bundle product.
item_list_tree[][item_name] string The name of the bundle.
item_list_tree[][item_sku] string The SKU of the bundle.
item_list_tree[][item_barcode] string The Barcode of the bundle.
item_list_tree[][item_qty] integer The total quantity of the bundle.
item_list_tree[][item_expiry_date] string The expiry date of the bundle.
item_list_tree[][retrieving_type] string The outbound type: item_out, pallet_out, piece_out, bundle_out.
item_list_tree[][retrieving_type_label] string The name of the outbound type.
item_list_tree[][serial_number] array Array of serial number.
item_list_tree[][children] array Array of the products that containing in the bundle. The structure is as same as item_list, the item_qty represent the total quantity of the order, not referring to each bundle.
logistics array Array of logistics information.
logistics[][logistics_vendor] string The name of logistic vendor.
logistics[][logistics] string The logistic method.
logistics[][logistics_status] string The status of the logistic.
logistics[][logistics_status_label] string The name of status of the logistic.
logistics[][logistics_code] string The tracking code of the logistic.
logistics[][logistics_log] array The history flow of the logistic.

Cancel An Order

Response:

{
"status": 200,
"message": "",
"data": 1001,
}

Cancel an order by using Order ID / Custom Order Id.

HTTP Request

GET /2020-11/orders/

Example:
GET /2020-11/orders/?order_id=1001

URL Parameters

Parameter Description Required
order_id Order ID of Boxful Fulfillment System. *Remarks 1
custom_order_id User defined Custom Order ID. *Remarks 1

*Remarks 1: Please give either one of above for searching.

Response Schema:

Type Description
integer Order ID of OMS.

Storage

Get Storage Information.

Get Stored List

Response:

{
"status": 200,
"message": "",
"data": [
{
"goods_id": 2,
"item_shipment_id": 1,
"item_label": "商品2",
"item_sku": "SKU2",
"item_barcode": "23456",
"item_desc": "Description2",
"store_date": "2020-05-21",
"expiry_date": null,
"list": [
{
"retrieving_type": "item_out",
"goods_status": "normal",
"goods_status_label": "Normal",
"count": 6,
"shipment_status": "ready_to_outbound",
"shipment_status_label": "Outbound Request Approved"
}
]
},
{
"goods_id": 3,
"item_shipment_id": 2,
"item_label": "商品3",
"item_sku": "SKU3",
"item_barcode": "34567",
"item_desc": "Description3",
"store_date": "2020-05-21",
"expiry_date": null,
"list": [
{
"retrieving_type": "piece_out",
"goods_status": "normal",
"goods_status_label": "Normal",
"count": 9,
"shipment_status": "able_to_outbound",
"shipment_status_label": "Outbound Available"
},
{
"retrieving_type": "piece_out",
"goods_status": "normal",
"goods_status_label": "Normal",
"count": 4,
"shipment_status": "ready_to_outbound",
"shipment_status_label": "Outbound Request Approved"
}
]
},
{
"goods_id": 6,
"item_shipment_id": 4,
"item_label": "測試1",
"item_sku": "test_1",
"item_barcode": "15918693785010149479",
"item_desc": "this is test 1",
"store_date": "2020-06-11",
"expiry_date": "2020-11-30",
"list": [
{
"retrieving_type": "piece_out",
"goods_status": "normal",
"goods_status_label": "Normal",
"count": 24,
"shipment_status": "able_to_outbound",
"shipment_status_label": "Outbound Available"
},
{
"retrieving_type": "piece_out",
"goods_status": "normal",
"goods_status_label": "Normal",
"count": 5,
"shipment_status": "ready_to_outbound",
"shipment_status_label": "Outbound Request Approved"
}
]
}
]
}

Get a list of items that are storing in Boxful Fulfillment.

HTTP Request

GET /2020-11/storage

Response Schema:

Key Type Description
goods_id integer Good Id which is for boxful internal use.
item_shipment_id integer shopment Id which is for boxful internal use.
item_label string Product’s name.
item_sku string Product’s SKU.
item_barcode string Product’s barcode.
item_desc string Product’s description.
store_date string The date of the products being stored.
expiry_date string The expiry date of the product.
list array Array of the storing information of the product in details.
list[][retrieving_type] string The outbound type: item_out, pallet_out, piece_out, bundle_out.
list[][goods_status] string The quality status of the product.
list[][goods_status_label] string The name of quality status of the product.
list[][count] integer The total quantity in storage of the product.
list[][shipment_status] string The status of shipment.
list[][shipment_status_label] string The name of status of shipment.

Get Stored List by SKU

Response:

{
"status": 200,
"message": "",
"data": {
"goods_id": 6,
"item_shipment_id": 4,
"item_label": "測試1",
"item_sku": "test_1",
"item_barcode": "15918693785010149479",
"item_desc": "this is test 1",
"store_date": "2020-06-11",
"expiry_date": "2020-11-30",
"list": [
{
"retrieving_type": "piece_out",
"goods_status": "normal",
"goods_status_label": "Normal",
"count": 24,
"shipment_status": "able_to_outbound",
"shipment_status_label": "Outbound Available"
},
{
"retrieving_type": "piece_out",
"goods_status": "normal",
"goods_status_label": "Normal",
"count": 5,
"shipment_status": "ready_to_outbound",
"shipment_status_label": "Outbound Request Approved"
}
]
}
}

Get a list of item by SKU that are storing in Boxful Fulfillment.

HTTP Request

GET /2020-11/storage/{SKU}

Response Schema:

Key Type Description
goods_id integer Good Id which is for boxful internal use.
item_shipment_id integer shopment Id which is for boxful internal use.
item_label string Product’s name.
item_sku string Product’s SKU.
item_barcode string Product’s barcode.
item_desc string Product’s description.
store_date string The date of the products being stored.
expiry_date string The expiry date of the product.
list array Array of the storing information of the product in details.
list[][retrieving_type] string The outbound type: item_out, pallet_out, piece_out, bundle_out.
list[][goods_status] string The quality status of the product.
list[][goods_status_label] string The name of quality status of the product.
list[][count] integer The total quantity in storage of the product.
list[][shipment_status] string The status of shipment.
list[][shipment_status_label] string The name of status of shipment.

Errors

The Boxful Fulfillment API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request has something wrong
401 Unauthorized – Your API key is wrong
403 Forbidden – The requested is hidden for administrators only
404 Not Found – The specified endpoint could not be found
405 Method Not Allowed – You tried to access with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many times! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.