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 [email protected].
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_HereUser-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. |