Introduction
Welcome to the Boxme API! You can use our API to access Boxme API endpoints.
Getting started
To make things easier for you, this guide would help you step by step to integrate with Boxme API.
Get an API key - Register a test account and generate API key
Location data - All our locations data by each market
Create products - You can use API to create products or batch import by excel in OMS
Get stock API - You can get real-time stock information across warehouses
Make inbound shipment - Used to create POs in our system
Create outbound B2C orders - Have some different between flow for orders delivery by Boxme's intergrated courier and self delivery, delivery by marketplace. Please checkout this guide to get more details.
API Call Flows
Changelog
Version 2.2 (01/08/2022)
- Add API and order status flow
- Add API to get stock level
- Location data in excel
Version 2.1
- Add Webhook api
- Add Get list orders status
- Add Boxme warehouse China
Version 2.0
- Release 01/08/2018
Authentication
Get a key
Before you can start using our APIs, you need an API key. It's easy. Just visit seller center and sign in with your account. Next step go to Settings menu -> Intergration to create API key.
Once you've activated your key, you're ready to roll.
Sandbox environment
Oms system: https://sandbox.boxme.asia
API URL: https://sandbox.boxme.asia/api/
Account : [email protected]
Password : 123456a@
API key : 424d8beddf6fcaca4ad4bcecc4dff0d6057c4116987a4a8c94336aa56700c9ba
Postman: Try with Postman
Production environment
Oms system: https://oms.boxme.asia
API URL: https://s.boxme.asia/api/
Using Boxme API key
To use the Boxme API key, construct a normal HTTPS request and include an Authorization
header with the value of Token. Signing is not required.
Example:
Authorization: Token 424d0db4e09024c3f29120972ddb747d34e721941e33bace61eb6fced161ac85
Please contact us if you have any questions [email protected].
Location
Get List Country
import requests
url = "https://sandbox.boxme.asia/api/v1/locations/countries/"
headers = {
'content-type': "application/json",
}
response = requests.request("GET", url)
curl "https://sandbox.boxme.asia/api/v1/locations/countries/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"country_code": "AF",
"country_name": "Afghanistan",
"phone_code": 93,
"required_zipcode": false,
"currency": "AFA"
},
{
"id": 2,
"country_code": "AL",
"country_name": "Albania",
"phone_code": 355,
"required_zipcode": false,
"currency": "ALL"
},
{
"id": 3,
"country_code": "DZ",
"country_name": "Algeria",
"phone_code": 213,
"required_zipcode": true,
"currency": "DZD"
},
{
"id": 4,
"country_code": "AS",
"country_name": "American Samoa",
"phone_code": 1684,
"required_zipcode": true,
"currency": "USD"
},
{
"id": 5,
"country_code": "AD",
"country_name": "Andorra",
"phone_code": 376,
"required_zipcode": true,
"currency": "ADP"
},
{
"id": 6,
"country_code": "AO",
"country_name": "Angola",
"phone_code": 244,
"required_zipcode": false,
"currency": "AON"
},
{
"id": 7,
"country_code": "AI",
"country_name": "Anguilla",
"phone_code": 1264,
"required_zipcode": false,
"currency": "XCD"
}
.......
]
}
Get list country in boxme system
HTTP Request
GET https://sandbox.boxme.asia/api/v1/locations/countries/
Get List Province & State
import requests
url = "https://sandbox.boxme.asia/api/v1/locations/countries/MY/provinces/"
headers = {
'content-type': "application/json",
}
response = requests.request("GET", url)
curl "https://sandbox.boxme.asia/api/v1/locations/countries/MY/provinces/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": [
{
"id": 175,
"country_code": "MY",
"code": "",
"province_name": "Kedah",
"province_name_local": "Kedah",
"province_name_convert": "kedah"
},
{
"id": 176,
"country_code": "MY",
"code": "",
"province_name": "Kelantan",
"province_name_local": "Kelantan",
"province_name_convert": "kelantan"
},
{
"id": 177,
"country_code": "MY",
"code": "",
"province_name": "Kuala Lumpur",
"province_name_local": "Kuala Lumpur",
"province_name_convert": "kualalumpur"
},
{
"id": 178,
"country_code": "MY",
"code": "",
"province_name": "Labuan",
"province_name_local": "Labuan",
"province_name_convert": "labuan"
},
{
"id": 179,
"country_code": "MY",
"code": "",
"province_name": "Melaka",
"province_name_local": "Melaka",
"province_name_convert": "melaka"
}
.............
]
}
Get list country in boxme system
HTTP Request
GET https://sandbox.boxme.asia/api/v1/locations/countries/MY/provinces/
Get List District
import requests
url = "https://sandbox.boxme.asia/api/v1/locations/countries/MY/179/district/"
headers = {
'content-type': "application/json",
}
response = requests.request("GET", url)
curl "https://sandbox.boxme.asia/api/v1/locations/countries/MY/179/district/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": [
{
"id": 3004,
"country_code": "MY",
"province": 179,
"district_name": "Air Keroh",
"district_name_local": "Air Keroh",
"code": "",
"district_name_convert": "airkeroh",
"area": 0
},
{
"id": 3005,
"country_code": "MY",
"province": 179,
"district_name": "Alor Gajah",
"district_name_local": "Alor Gajah",
"code": "",
"district_name_convert": "alorgajah",
"area": 1
},
{
"id": 3006,
"country_code": "MY",
"province": 179,
"district_name": "Asahan",
"district_name_local": "Asahan",
"code": "",
"district_name_convert": "asahan",
"area": 0
},
.............
]
}
Get list district
HTTP Request
GET https://sandbox.boxme.asia/api/v1/locations/countries/{country_code}/{province_id}/district/
Request Response
Parameter | Data Type | Required | Description |
---|---|---|---|
id |
integer | yes | District ID |
country_code |
string | yes | Country code (ISO 2-char country code) |
province |
string | yes | Province ID |
district_name |
string | yes | District name |
district_name_local |
string | yes | District local name |
area |
integer | yes | 1. Center of province, state |
Lookup Zipcode
import requests
url = "http://sandbox.boxme.asia/api/v1/locations/lookup-zipcode/MY/8210/"
headers = {
'content-type': "application/json",
}
response = requests.request("GET", url)
curl "http://sandbox.boxme.asia/api/v1/locations/lookup-zipcode/MY/8210/"
The above command returns JSON structured like this:
{
"data": [
{
"id": 1032,
"country_code": "MY",
"province": 174,
"province_code": "",
"province_name": "Johor",
"district": 2883,
"district_name": "Ayer Baloi",
"zipcode": "82100",
},
{
"id": 1032,
"country_code": "MY",
"province": 174,
"province_code": "",
"province_name": "Johor",
"district": 2883,
"district_name": "Ayer Baloi",
"zipcode": "82100",
},
]
}
You can lookup provinces and districts belong to zipcode
HTTP Request
GET http://sandbox.boxme.asia/api/v1/locations/lookup-zipcode/{country_code}/{zipcode}
Request Response
Parameter | Data Type | Required | Description |
---|---|---|---|
id |
integer | yes | District ID |
country_code |
string | yes | Country code (ISO 2-char country code) |
province |
string | yes | Province ID |
province_code |
string | yes | Province name |
province_name |
string | yes | Province local name |
district |
string | yes | District ID |
district_name |
string | yes | District name |
zipcode |
string | yes | zipcode |
Pickup Address
Boxme warehouse
Warehouse | Warehouse name | Warehouse country |
---|---|---|
BMVN_HN_TT | Boxme Tan Trieu | Ha Noi, VietNam |
BMVN_HCM_TT | Boxme Tan Thuan | Ho Chi Minh, VietNam |
BMVN_HCM_TP | Boxme Tan Binh | Ho Chi Minh, VietNam |
BMTH_KRB | Boxme Lat Krabang | Bangkok, Thailand |
BMID_ST | Boxme Cengkareng JKT | Jakarta, Indonesia |
BMMY_SB | Boxme Emporis Damansara | Selangor, Malaysia |
BMPH_CLB | Boxme Bicutan | Laguna, Philippines |
List Pickup Addresses
In Boxme system, the address included pick-up and return address of merchant.
HTTP Request
GET http://sandbox.boxme.asia/api/v1/sellers/addresses/
import requests
url = "http://sandbox.boxme.asia/api/v1/sellers/addresses/"
headers = {
'content-type': "application/json",
}
response = requests.request("GET", url)
curl "http://sandbox.boxme.asia/api/v1/sellers/addresses/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {
"count": 1,
"next": null,
"previous": null,
"results": [{
"id": 1,
"country": "VN",
"pickup_name": "Boxme Ha Noi-0906262181",
"name_contact": "Boxme Ha Noi",
"phone": "0906262181",
"province_id": 1,
"district_id": 7,
"commune_id": 0,
"zipcode": "",
"address": "18 Tam Trinh, Minh Khai, Hai Bà Trưng, Hà Nội, Việt Nam, 18 Tam Trinh, Mai Động, Hai Bà Trưng, Hà Nội 90001, Vietnam,Quận Hai Bà Trưng, Hà Nội",
"lat": "0.000000",
"lng": "0.000000",
"active": 1
}]
},
"error": false,
"error_code": "",
"messages": "",
"total": 1
}
Request Query
Parameter | Data Type | Required | Description |
---|---|---|---|
address_type |
integer | yes | Type of address 1 is pick-up address 2 is return address |
page_size |
integer | no | Total address display once page. Default: 20 |
page |
integer | no | Page number |
Request Response
Parameter | Data Type | Description |
---|---|---|
id |
integer | Address ID |
country |
string | Address country code (ISO 2-char country code) |
pickup_name |
string | Address name |
name_contact |
string | Address contact name |
phone |
string | Address contact phone |
province_id |
integer | State, Province ID. Refer to Location |
district_id |
integer | District ID. Refer to Location |
zipcode |
string | Address zipcode |
address |
string | Address detail |
lat |
geo | Latitude |
lng |
geo | Longitude |
active |
integer | Active or not |
Add Pickup Addresses
import requests
url = "https://sandbox.boxme.asia/api/v1/sellers/addresses/"
payload = {
"pickup_code": "",
"pickup_name": "KHO BMVN_HCM",
"name_contact": "Sandbox",
"phone": "0987654321",
"address": "",
"country": "VN",
"province_id": 79,
"district_id": 886,
"commune_id": 0,
"zipcode": "",
"priority": 1,
"ff_center": 1,
"ff_center_code": "BMVN_HCM",
"address_type": 1
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v1/sellers/addresses/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {
"pickup_id": 25898
},
"error": false,
"error_code": "",
"messages": "Create address success",
"total": 0
}
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
pickup_code |
string | yes | Pickup code ( your pickup code) |
pickup_name |
string | yes | Pickup name |
name_contact |
string | yes | Name contact pickup |
phone |
string | yes | Phone contact pickup |
address |
string | yes | Address pickup |
country |
string | yes | VN , ID , TH , MY , PH |
province_id |
int | yes | Province id pickup |
district_id |
int | yes | District id pickup |
zipcode |
string | yes | Zipcode pickup |
priority |
string | yes | Default address pickup |
ff_center |
int | yes | Use fulfillment center of BOXME ( 1: Yes, 0: No) |
ff_center_code |
string | yes | Fulfillment code of BOXME (See list below) |
Result
Key | Data Type | Description |
---|---|---|
messages |
string | API Respone message |
error_code |
string | API error code |
error |
boolean | True/False |
data |
object | . |
pickup_id |
string | Pickup id |
Shipment
Get Shipment List
import requests
url = "http://sandbox.boxme.asia/api/v1/sellers/shipments/list/ "
payload = {
"create_from": 1644771600,
"create_to": 1646067599,
"page": 1,
"page_size": 50
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("GET", url, data=payload, headers=headers)
curl "http://sandbox.boxme.asia/api/v1/sellers/shipments/list/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data":{
"results":[
{
"id":96814,
"country":"VN",
"shipment_code":"SM-VN-42-98887206",
"tracking_number":"",
"shipping_method":"Inbound",
"create_by":42,
"update_by":42,
"currency":"",
"amount":"",
"money_collect":"",
"order_fee":"",
"estimate_delivery":"",
"service":{
},
"courier":{
},
"create_by_user":{
"create_by":42,
"username":"David Nguyen",
"phone":"02312312311",
"email":"[email protected]"
},
"sender":{
"sender_id":42,
"username":"David Nguyen",
"phone":"02312312311",
"email":"[email protected]"
},
"pickup":{
"name":"0123456789",
"phone":"098765432",
"country":"VN",
"province_id":1,
"province":"Hà Nội (MB)",
"district_id":20,
"district":"Huyện Thanh Trì",
"address":"Kho Boxme, Lô D10-11, Cụm sản xuất làng nghề tập trung, Xã Tân Triều, Thanh Trì, Hà Nội",
"ff_center_code":"BMVN_HN_TT",
"pickup_name":"BOXME TAN TRIEU"
},
"fullfillment":{
"name":"0123456789",
"phone":"098765432",
"country":"VN",
"province_id":1,
"province":"Hà Nội (MB)",
"district_id":20,
"district":"Huyện Thanh Trì",
"address":"Kho Boxme, Lô D10-11, Cụm sản xuất làng nghề tập trung, Xã Tân Triều, Thanh Trì, Hà Nội",
"ff_center_code":"BMVN_HN_TT",
"pickup_name":"BOXME TAN TRIEU"
},
"status":{
"status_code":4,
"status_name":"In-transit",
"label_status":"badge badge-info"
},
"statistic":{
"quantity":1,
"quantity_received":0,
"quantity_damaged":0,
"quantity_cancelled":0,
"quantity_barcode":0,
"quantity_sublabel":0
},
"volume":"12812904",
"weight":324,
"check_update":0,
"deleted":0,
"created_time":1645587206.0,
"updated_time":1645587227.0,
"expect_time":0.0,
"approved_time":1645587206.0,
"successed_time":0.0,
"received_time":0.0,
"shipment_fee":{
"id":96814,
"fee_value":0.0,
"fee_code":"handling_fee",
"paid":0,
"paid_time":0,
"currency":"VND"
},
"list_shipment_fee":{
"total":550.0,
"barcode_sticker":550.0,
"handling_fee":0.0
},
"description":"23423423432",
"is_b2b":0,
"complaints_note":"",
"confirmed_status_display":"Waiting for confirmation",
"confirmed_status":0,
"confirmed_time":0.0
}
],
"count":1,
"next":"",
"previous":""
},
"error":false,
"error_code":"",
"messages":"",
"request_id":1646295435,
"total":1
}
Get Shipment List
HTTP Request
GET http://sandbox.boxme.asia/api/v1/sellers/shipments/list/
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
create_from |
integer | yes | Unix timestamp |
create_to |
integer | yes | Unix timestamp |
shipping_method |
integer | yes | 1: Inbound 4: Removal |
page |
integer | yes | Page number (default: 1) |
page_size |
integer | yes | Number of record returned (max: 100) |
Request Response
Parameter | Data Type | Required | Description |
---|---|---|---|
results |
list | yes | The list of shipment |
Get Shipment Detail
import requests
url = "https://sandbox.boxme.asia/api/v1/sellers/shipments/detail/{shipment_code}/"
payload = {
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("GET", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v1/sellers/shipments/detail/{shipment_code}/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data":{
"id":97614,
"country":"VN",
"shipment_code":"SM-VN-331529-64387069",
"tracking_number":"123213",
"create_by":331529,
"update_by":331529,
"shipping_type":2,
"pickup":{
"id":350165,
"name":"Boxme Tan Thuan - Ho Chi Minh",
"phone":"840329929992",
"province":"TP. Hồ Chí Minh",
"province_id":79,
"district":"Quận 7",
"district_id":778,
"commune":"Phường Tân Thuận Đông",
"commune_id":27466,
"address":"Boxme Tân Thuận - Kho D1-2, Đường N3, Khu thương mại bắc , Khu chế xuất Tân Thuận, Phường Tân Thuận Đông, Quận 7, Thành phố Hồ Chí Minh",
"country":"Vietnam",
"warehouse_info":{
"name":"Boxme Tan Thuan - Ho Chi Minh",
"code":"BMVN_HCM_TT",
"phone":"0988352662",
"address":"Boxme Tân Thuận - Kho D1-2, Đường N3, Khu thương mại bắc , Khu chế xuất Tân Thuận, Phường Tân Thuận Đông, Quận 7, Thành phố Hồ Chí Minh"
}
},
"fullfillment":{
"id":350165,
"name":"Boxme Tan Thuan - Ho Chi Minh",
"phone":"840329929992",
"province":"TP. Hồ Chí Minh",
"province_id":79,
"district":"Quận 7",
"district_id":778,
"commune":"Phường Tân Thuận Đông",
"commune_id":27466,
"address":"Boxme Tân Thuận - Kho D1-2, Đường N3, Khu thương mại bắc , Khu chế xuất Tân Thuận, Phường Tân Thuận Đông, Quận 7, Thành phố Hồ Chí Minh",
"country":"Vietnam",
"warehouse_info":{
"name":"Boxme Tan Thuan - Ho Chi Minh",
"code":"BMVN_HCM_TT",
"phone":"0988352662",
"address":"Boxme Tân Thuận - Kho D1-2, Đường N3, Khu thương mại bắc , Khu chế xuất Tân Thuận, Phường Tân Thuận Đông, Quận 7, Thành phố Hồ Chí Minh"
}
},
"shipping_method":1,
"volume":"1000",
"weight":1,
"status":{
"status_code":"4",
"status_name":"In-transit",
"label_status":"badge badge-info"
},
"deleted":0,
"check_update":0,
"created_time":1646187069,
"updated_time":1646187090,
"successed_time":0,
"expect_time":1646154000,
"approved_time":1646187069,
"received_time":0,
"sync":1,
"shipment_fee":{
"handling_fee":0,
"currency":"VND",
"inspection_fee":540000
},
"warehouse_number":"",
"ff_center_code":"BMVN_HCM_TT",
"print_url":"",
"box_label":"",
"description":"Boxme Test - Kien",
"is_b2b":false,
"unloading":false,
"approved_log":{
},
"confirmed_time":0,
"confirmed_status":0,
"confirmed_status_display":"Waiting for confirmation",
"reason":"",
"packages":[
{
"code":"#1001",
"weight":1,
"volume":"10x10x10",
"cbm":0.001,
"created_time":1646187069,
"description":"",
"total_item":1000
}
],
"statistics":{
"total_change_info":0,
"total_damaged":0,
"total_change_date":0,
"total_barcode":0,
"total_cbm":0,
"cbm_create":1.0
},
"warehouse_staff":{
},
"shipment_document":[
],
"inspection":true,
"inspection_note":""
},
"error":false,
"error_code":"",
"messages":"",
"request_id":1649053965,
"total":0
}
Get Shipment Detail
HTTP Request
GET https://sandbox.boxme.asia/api/v1/sellers/shipments/detail/{shipment_code}/
Request Body
Request Response
Parameter | Data Type | Required | Description |
---|---|---|---|
data |
object | yes | Detail of shipment |
Create Inbound Shipment
import requests
url = "https://sandbox.boxme.asia/api/v1/sellers/shipments/create/"
payload = {
"shipping_method": 1,
"source": 0,
"status": 2,
"pickup_id": 339187,
"ff_id": 339187,
"inspection": 1,
"priority_inbound": 1,
"inspection_note": "Inspection not",
"products": [
{
"sku": "SKU01",
"bsin": "BSN33152918743433",
"quantity": 1,
"weight": 135,
"amount": "239000.00",
"boxno": "#1001"
}
],
"packages": [
{
"code": "#1001",
"weight": 10,
"width": 10,
"length": 10,
"height": 10
}
],
"tracking": {
"type": 2,
"tracking_number": "ABC123"
},
"description": "Shipment note",
"products_serial": [],
"arrive_time": 1659373200,
"documents": [
{
"file_name": "issue_export_421659410477.xlsx",
"url": "https://storage.googleapis.com/boxme-cloud/ticket/2022/08/issue_export_421659410477_ITNdrw_202208.xlsx"
}
]
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v1/sellers/shipments/create"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {
"shipment_code": "SM-VN-331529-62650234",
"list_tracking": [],
"fee": {
"handling_fee": 0.0,
"priority_inbound_fee": 540.0
}
},
"error": false,
"error_code": "",
"messages": "Create shipment success.",
"request_id": 1659450235,
"total": 0
}
HTTP Request
POST https://sandbox.boxme.asia/api/v1/sellers/shipments/create/
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
shipping_method |
number | yes | 1. Inbound shipment |
status |
number | yes | 2 Create and approved, 1.Create and approve after |
pickup_id |
number | yes | Your warehouse id. Please see list in "General settings" => "Business" =>"Pickup address". |
ff_id |
number | yes | Boxme warehouse id ( BMVN_HN, BMID_BKS...). Please see list in "General settings" => "Business" =>"Pickup address". |
products |
list | yes | List product for requests. Please refer products |
packages |
list | yes | List packages for requests. Please refer packages |
tracking |
object | yes | Your reference tracking information Please refer tracking |
inspection |
number | yes | Co-inspection at Boxme warehouse (1: Yes, 2: No) |
priority_inbound |
number | yes | Priority inbound (1: Yes, 2: No) |
products detail
Parameter | Data Type | Required | Description |
---|---|---|---|
sku |
string | yes | Your product SKU. |
quantity |
number | yes | Quantity |
weight |
number | yes | Weight product. |
amount |
number | yes | Product amount |
boxno |
string | yes | Box code containing the product packages |
Packages detail
Parameter | Data Type | Required | Description |
---|---|---|---|
code |
string | yes | Box code contains |
weight |
number | yes | Weight box |
width |
number | yes | Width box. |
length |
number | yes | Length box |
height |
number | yes | Height box |
Tracking detail
Parameter | Data Type | Required | Description |
---|---|---|---|
type |
number | yes | 1. Shipping by Boxme, 2.Shipping by yourself |
tracking_number |
string | no | Your PO Code |
Request Response
Key | Data Type | Description |
---|---|---|
messages |
string | API Respone message |
error_code |
string | API error code |
error |
boolean | True/False |
data |
object | . |
shipment_code |
string | Shipment code |
Create Removal Shipment
import requests
url = "https://sandbox.boxme.asia/api/v1/sellers/shipments/create/"
payload = {
"boxes": [],
"ff_id": 339187,
"packages": [],
"pallets": [],
"pickup_id": 339187,
"arrive_time": 1660237200,
"description": "Note for pack",
"products": [
{
"bsin": "BSN33152918740973",
"quantity": 124,
"weight": 135,
"sku": "SKU09",
"condition_level": 1
}
],
"remove_method": 0,
"shipping_method": 4,
"status": 2,
"tracking": {
"estimate": "",
"tracking_number": "",
"type": 2,
"url": ""
}
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v1/sellers/shipments/create"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {
"shipment_code": "SM-VN-331529-62650234",
"list_tracking": [],
"fee": {
"handling_fee": 0.0,
"priority_inbound_fee": 540.0
}
},
"error": false,
"error_code": "",
"messages": "Create shipment success.",
"request_id": 1659450235,
"total": 0
}
HTTP Request
POST https://sandbox.boxme.asia/api/v1/sellers/shipments/create/
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
shipping_method |
number | yes | 4. Outbound shipment |
status |
number | yes | 2 Create and approved, 1.Create and approve after |
ff_id |
number | yes | Boxme warehouse id ( BMVN_HN, BMID_BKS...). Please see list in "General settings" => "Business" =>"Pickup address". |
products |
list | yes | List product for requests. Please refer products |
packages |
list | no | Leave blank array |
tracking |
object | yes | Your reference tracking information Please refer tracking |
products detail
Parameter | Data Type | Required | Description |
---|---|---|---|
sku |
string | yes | Your product SKU. |
quantity |
number | yes | Quantity |
weight |
number | yes | Weight product. |
amount |
number | yes | Product amount |
condition_level |
number | yes | 1. Good condition products, 2: D1, 3: D2, 3: D4 |
Tracking detail
Parameter | Data Type | Required | Description |
---|---|---|---|
type |
number | yes | 1. Shipping by Boxme, 2.Shipping by yourself |
tracking_number |
string | no | Your PO Code |
Request Response
Key | Data Type | Description |
---|---|---|
messages |
string | API Respone message |
error_code |
string | API error code |
error |
boolean | True/False |
data |
object | . |
shipment_code |
string | Shipment code |
Approved/Cancel Shipment
import requests
url = "https://sandbox.boxme.asia/api/v1/sellers/shipments/detail/{shipment_code}/"
payload = {
"status": 5
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("PUT", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v1/sellers/shipments/detail/{shipment_code}/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {},
"error": false,
"error_code": "",
"messages": "Update shipment code: {shipment_code} is success",
"total": 0
}
HTTP Request
PUT https://sandbox.boxme.asia/api/v1/sellers/shipments/detail/{shipment_code}/
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
status |
number | yes | 2 Approved, 5.Cancel Shipment |
Request Response
Key | Data Type | Description |
---|---|---|
messages |
string | API Respone message |
error_code |
string | API error code |
error |
boolean | True/False |
data |
object | . |
shipment_code |
string | Shipment code |
Products
Create an product
import requests
import json
url = "https://sandbox.boxme.asia/api/v2/sellers/products/create"
payload = json.dumps({
"name": "Product 2",
"seller_sku": "SKU00001",
"barcode_manufacturer": "2999999929292",
"category_id": 3,
"desc": "Color: red, check all corner",
"price_sale": 200000,
"price": 10000,
"is_digital": 0,
"min_quantity": 100,
"warehouse_condition": 1,
"pack_with_bubble": 1,
"pack_material": 1,
"weight": 500,
"volume": "20x20x20",
"price_wholesale": 0,
"image_data": [
"https://images.unsplash.com/photo-1505740420928-5e560c06d30e?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxzZWFyY2h8M3x8cHJvZHVjdHxlbnwwfHwwfHw%3D&w=1000&q=80"
],
"manage_by_serial_number": False,
"require_expire": 0,
"outbound_strategy": 1,
"documents": [],
"expiration_time": None,
"expiry_threshold": None,
"is_fragile": True,
"use_shredded_paper": False,
"batch_control": True,
"uom": 1
})
headers = {
'Authorization': 'Token xxxxxx',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
HTTP Request
POST https://sandbox.boxme.asia/api/v2/sellers/products/create
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
name |
string | yes | Product name. |
seller_sku |
string | yes | Product SKU |
barcode_manufacturer |
string | yes | Manufacturer barcode |
category_id |
number | yes | Product category. Refer to product categories |
desc |
string | yes | Product description |
price_sale |
float | yes | Sale price |
price |
float | no | Cost Price |
price_wholesale |
float | no | Wholsale price |
is_digital |
number | yes | Digital or Physical product (default: 0 - physical) |
min_quantity |
number | yes | Alerts for item quantity lower |
warehouse_condition |
integer | yes | Storage condition (1: Normal storage, 2: Air storage) |
pack_with_bubble |
integer | yes | Protective packing with bubble (1: Yes, 2: No), extra charges will be applied |
pack_material |
number | yes | Material for packing (1: Bag, 2: Box, 3: Bubble wrap, 4: Not use packing materials) |
weight |
number | yes | Actual weight by gram |
volume |
string | yes | Product dimension (WxHxL), example 20x10x20 |
image_data |
list | yes | List of product images |
manage_by_serial_number |
boolean | yes | Manage product by serial number. |
require_expire |
boolean | yes | Manage product expiry date. (1: Yes, 0: No) |
outbound_strategy |
number | yes | Outbound strategy (1: FIFO, 2: LIFO, 3: FEFO, 4: Custom) |
expiration_time |
number | yes | Shelf life (months) |
expiry_threshold |
number | yes | If expiry dates meet this threshold you can't make outbound orders |
is_fragile |
boolean | yes | We will do special process to storage and stick fragile sticker or tape |
use_shredded_paper |
boolean | yes | Protective packing with shredded paper |
batch_control |
boolean | yes | Manage products by Batch / LOT |
uom |
number | yes | Products units (1: Piece, 2: Box, 3: Package, 4: Set) |
Product categories
Category ID | Description |
---|---|
1 | Mobiles |
2 | Tablets |
3 | Computers & Laptops |
4 | Cameras |
5 | Accessories (no-battery) |
6 | Accessories (battery) |
7 | Health & Beauty |
8 | Fashion |
9 | Watches |
10 | Jewelry |
11 | Dry Food & Supplements |
12 | Home & Appliances |
13 | Home & Garden |
14 | Toys |
15 | Sports |
16 | Luggage |
17 | Audio Video |
18 | Documents |
19 | Gaming |
20 | Books & Collectibles |
21 | Pet Accessories |
22 | Comestic |
Get stock
You can get real-time stock information across warehouses
import requests
url = "https://sandbox/api/v1/sellers/products_inventory_by_sku/{SKU}/"
payload = ""
headers = {
'Authorization': 'Token xxxxxx'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
The above command returns JSON structured like this:
{
"data": {
"count": 1,
"next": "",
"previous": "",
"results": [
{
"country": "VN",
"seller_id": 195,
"pickup_id": 154344,
"pickup_name": "BOXME TÂN BÌNH",
"seller_sku": "BTM-714",
"quantity_in_stock": 130,
"damaged_in_stock": 0,
"waiting_outbound": 0
}
]
},
"error": false,
"error_code": "",
"messages": "",
"request_id": 1659435953,
"total": 1
}
HTTP Request
GET https://sandbox.boxme.asia/api/v1/sellers/products_inventory_by_sku/{SKU}/
Request Body
Follow example on the right side.
Request Response
Parameter | Data Type | Description |
---|---|---|
quantity_in_stock |
integer | Total good products condition |
damaged_in_stock |
integer | Total damaged products |
waiting_outbound |
integer | Total products waiting to outbound |
fulfillable quantity
= quantity_in_stock
- waiting_outbound
Shipping Rates
Calculate
import requests
url = "https://sandbox.boxme.asia/api/v1/courier/pricing/calculate"
payload = {
"ship_from": {
"country": "TH",
"pickup_id": 190
},
"ship_to": {
"contact_name": "Kitti Settanyakit",
"address": "ม.เคซีเนเชอรอลซิิตี้ ถนนกาญจนาภ ิเษก แขวงสะพานสูง",
"phone": "0863364084",
"country": "TH",
"province": 190,
"district": 3389,
"zipcode": 10240
},
"shipments": {
"content": "Product name",
"total_parcel": 1,
"total_amount": 120,
"chargeable_weight": 1000,
"description": "Call customer before deliver",
"parcels": [
{
"amount": 120,
"description": "",
"dg_code": null,
"dimension": {
"width": 17,
"height": 6,
"length": 11
},
"hs_code": "",
"images": [],
"inspect_note": "",
"items": [
{
"sku": "",
"origin_country": "TH",
"name": "Product name",
"weight": 1000,
"amount": 120,
"quantity": 1,
"desciption": "Men T-Shirt",
"label_code": ""
}
],
"referral_code": "",
"weight": 1000,
"dg_cod": ""
}
]
},
"config": {
"order_type": "normal",
"return_mode": 1,
"insurance": "N",
"document": "N",
"currency": "THB",
"unit_metric": "metric"
},
"payment": {
"fee_paid_by": "sender",
"tax_paid_by": "receiver",
"cod_amount": 0
},
"referral": {
"order_number": "CUSTOMER ORER NUMBER"
}
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v1/courier/pricing/calculate"
-H "Authorization: api key"
The above command returns JSON structured like this:
[
{
"data": {
"couriers": [
{
"total_fee": 527957.76,
"shipping_fee": 527957.76,
"tax": 0,
"duty": 0,
"vas": {
"cod": 0,
"insurance": 0,
"checking": 0
},
"discount": 0,
"cod_value": 0,
"min_delivery_time": 1,
"max_delivery_time": 2,
"currency": "VND",
"handover_options": "dropoff,pickup",
"handover_policy": "Free pickup",
"courier_name": "DHL",
"courier_id": 17,
"courier_logo": "http://v2.boxme.vn/assets/images/courier/dhl.svg",
"service_code": "DCM",
"service_name": "DHL Express WorldWide(Documents up to 2.0 KG)",
"insurance_policy": "http://boxme.asia/insurance-policy-url",
"dropoff_point": "http://boxme.asia/drop-off/vtp",
"delivery_time_rank": 1,
"fee_rank": 1,
"rating": 1
},
{
"total_fee": 551078.88,
"shipping_fee": 551078.88,
"tax": 0,
"duty": 0,
"vas": {
"cod": 0,
"insurance": 0
},
"discount": 0,
"cod_value": 0,
"min_delivery_time": 1,
"max_delivery_time": 2,
"currency": "VND",
"handover_options": "dropoff,pickup",
"handover_policy": "Free pickup",
"courier_name": "DHL",
"courier_id": 17,
"courier_logo": "http://v2.boxme.vn/assets/images/courier/dhl.svg",
"service_code": "NDC",
"service_name": "DHL Express WorldWide(Non-documents from 0.5 KG & Documents from 2.5 KG)",
"insurance_policy": "http://boxme.asia/insurance-policy-url",
"dropoff_point": "http://boxme.asia/drop-off/vtp",
"delivery_time_rank": 2,
"fee_rank": 2,
"rating": 2
}
]
},
"error": false,
"error_code": "",
"messages": "Calculate fee successfully",
"total": 0
}
]
Get shipping fee
HTTP Request
POST https://sandbox.boxme.asia/api/v1/courier/pricing/calculate
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
ship_from |
object | yes | Pickup address details. |
country |
string | yes | Shipper Country code (ISO 2-char country code) |
pickup_id |
integer | yes | Pickup id get from your account. |
ship_to |
object | yes | Consignee address details. |
contact_name |
string | yes | Consignee name. |
address |
string | yes | Consignee address line 1. |
phone |
string | yes | Consignee Phone number. Accepted special characters are : - ( ) # + .. |
country |
string | yes | Consignee Country code (ISO 2-char country code) |
province |
integer | yes | Consignee state or province id. Refer to Location |
district |
integer | no | Consignee district id. Refer to Location Only required for Viet Nam customers |
zipcode |
string | yes | Consignee zipcode. |
shipments |
object | yes | Shipments details. |
content |
string | yes | Parcel key content. |
total_parcel |
integer | yes | Total parcel of shipments. |
total_amount |
decimal | yes | Total shipments amount. |
description |
string | no | Detail parcel description. |
chargeable_weight |
string | yes | Chargeable weight of shipment. |
config |
object | yes | Config informations. |
sort_mode |
interge | no | Sort by : best_price (default), best_time , best_rating |
order_type |
string | yes | Order type : normal (default), cross_border , consolidate , fulfill |
return_mode |
interge | no | Return mode. 1: to pickup address (default) , 2 : to return address |
insurance |
string | no | Total shipments amount. Only accept Y or N |
document |
string | yes | Description. Only accept Y or N |
currency |
string | yes | 3-char ISO currency code for all monetary value fields. |
unit_metric |
string | no | metric or imperial |
payment |
object | yes | Payment informations. |
fee_paid_by |
string | yes | Default fee paid by sender , if you change to receiver then we will add fee to CoD amount. |
tax_paid_by |
string | yes | Default fee paid by receiver , if you change to sender then you will be charge (if any). |
cod_amount |
decimal | yes | Total CoD Amount(in 2 decimal points). We will calculate depend by fee_paid_by Formula: CoD Amount = cod_amount + total_fee (if fee_paid_by is receiver ). |
Orders
Get Order List
import requests
url = "http://sandbox.boxme.asia/api/v1/orders/list/"
payload = {
"create_from": 1644771600,
"create_to": 1646067599,
"page": 1,
"page_size": 50
}
headers = {
"content-type": "application/json",
"authorization": "api key",
}
response = requests.request("GET", url, data=payload, headers=headers)
curl "http://sandbox.boxme.asia/api/v1/orders/list/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data":{
"count":1,
"next":"",
"previous":"",
"results":[
{
"id":6298107,
"country":"VN",
"create_by":331529,
"seller_id":331529,
"platform":"",
"created_request_return":0,
"order_type":5,
"order_type_display":"Fulfill",
"order_number":"",
"tracking_number":"BM83841094915",
"label_token":"MDZiNDEwNWItODI3Yy00OTA5LTllNzYtMDg1YzE1YjkzOTI5",
"label_url":"",
"is_boxme_label":true,
"is_printed":0,
"courier_tracking_code":"",
"weight":10,
"over_weight":0,
"quantity":1,
"amount":"210000.00",
"money_collect":"0.00",
"crosscheck_id":0,
"invoice_id":0,
"tax_paid_by":2,
"status":700,
"currency":"VND",
"fulfillment":1,
"created_time":1645605632,
"updated_time":1645610717,
"accepted_time":1645605632,
"approved_time":0,
"packed_time":0,
"pickuped_time":0,
"first_delivery_attempt":0,
"successed_time":1645605679,
"approve_return_time":0,
"description":"",
"estimate_delivery":86400,
"estimate_delivery_to":0,
"receiver":{
"receiver_id":6359917,
"fullname":"Trần Thị Thu Thảo (Phát tận tay)",
"phone":"0907509568",
"phone_code":"",
"email":"",
"zipcode":"",
"country":"VN",
"province_id":79,
"district_id":774,
"commune_id":27340,
"address":"Công ty cổ phần BĐS Danh Khôi Á Châu, 63-67 An Điềm, phường 10, quận 5, Hồ Chí Minh",
"province":"TP. Hồ Chí Minh",
"district":"Quận 5",
"commune":"Phường 10"
},
"service_code":"BM_DBS",
"courier_id":52,
"pickup_id":345185,
"order_fee":7700.0,
"list_fee":[
{
"fee_code":"special_fee",
"fee_value":2200.0,
"currency":"VND",
"fee_name":"Phí DV đặc biệt"
},
{
"fee_code":"handover_fee",
"fee_value":2200.0,
"currency":"VND",
"fee_name":"Phí bàn giao"
},
{
"fee_code":"handling_fee",
"fee_value":3300.0,
"currency":"VND",
"fee_name":"Phí xử lý"
}
],
"total_cbm":0.001,
"parcels":[
{
"order_id":6298107,
"parcel_id":6304823,
"box_id":0,
"sku":"KIEN_TEST_1",
"bsin":"BSN33152905437334",
"quantity":1,
"dimension":"10x10x10",
"product_name":"Mặt nạ cao su cấp ẩm Dr Jart",
"amount":210000.0,
"currency":"VND",
"customs_value":210000.0
}
],
"customs_value":210000.0,
"parcel_serial":[
],
"obj_product_serial":{
},
"crosscheck_time_created":0,
"hybrid_courier_id":0,
"hybrid_service_code":"",
"campaign_code":"",
"seller":null,
"source":"",
"store_order_id":"",
"journey_update_time":null,
"journey_note":null,
"handover_time":0.0,
"warehouse_status":0,
"warehouse_status_display":"",
"external_courier":null,
"cbm":"0.0010",
"fulfillment_weight":167.0,
"expected_delivery":"",
"ff_center_code":"BMVN_HCM_TP",
"list_product_out_of_stock":null,
"status_name":"Cancelled by sellers",
"label_status":"badge badge-danger",
"pickup":{
"pickup_id":345185,
"user_name":"kien123",
"phone":"0326616817",
"country":"VN",
"province_id":79,
"province":"TP. Hồ Chí Minh",
"district_id":767,
"district":"Quận Tân Phú",
"commune_id":27013,
"commune":"Phường Tây Thạnh",
"address":"Kho Boxme, Lô II-1, Đường Số 1, Nhóm Công Nghiệp 2, Khu Công Nghiệp Tân Bình, Phường Tây Thạnh, Quận Tân Phú, TP. Hồ Chí Minh"
},
"courier":{
"prefix":"boxme",
"description":"",
"courier_id":52,
"name":"Boxme Express",
"logo":"https://app.omisell.com/assets/customize/images/courier/Boxme_EXPRESS.svg",
"url_track":"https://boxme.asia/en/trackntrace/?tracking_number="
},
"service":{
"courier_id":52,
"code":"BM_DBS",
"name":"Người bán tự vận chuyển",
"partner_code":"BM_DBS"
},
"crosscheck_estimate_time":0,
"return_tracking_number":"",
"origin_tracking_number":""
}
]
},
"error":false,
"error_code":"",
"messages":"",
"request_id":1646295633,
"total":1
}
Get Order List
HTTP Request
GET http://sandbox.boxme.asia/api/v1/orders/list/
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
create_from |
integer | yes | Unix timestamp |
key |
string | yes | Tracking number, order number, courier tracking to search |
create_to |
integer | yes | Unix timestamp |
update_from |
integer | no | Unix timestamp |
update_to |
integer | no | Unix timestamp |
page |
integer | yes | Page number (default: 1) |
page_size |
integer | yes | Number of record returned (max: 100) |
Request Response
Parameter | Data Type | Required | Description |
---|---|---|---|
results |
list | yes | The list of orders |
Get Order Return List
import requests
url = "http://sandbox.boxme.asia/api/v1/orders/order_return/list/ "
payload = {
"create_from": 1644771600,
"create_to": 1646067599,
"page": 1,
"page_size": 50
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("GET", url, data=payload, headers=headers)
curl "http://sandbox.boxme.asia/api/v1/orders/order_return/list/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"messages": "",
"data": {
"count": 10,
"results": []
},
"error": false,
"total": 0,
"error_code": ""
}
Get Order List
HTTP Request
GET http://sandbox.boxme.asia/api/v2/orders/order_return/list/
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
create_from |
integer | yes | Unix timestamp |
create_to |
integer | yes | Unix timestamp |
update_from |
integer | no | Unix timestamp |
update_to |
integer | no | Unix timestamp |
tracking_number |
string | yes | Tracking number to search |
product_status |
integer | yes | 0: Waiting receive 1: Waiting inspection 2: Restocked 4: Damaged / Lost 5: Cancelled |
page |
integer | yes | Page number (default: 1) |
page_size |
integer | yes | Number of record returned (max: 100) |
Request Response
Parameter | Data Type | Required | Description |
---|---|---|---|
results |
list | yes | The list of orders |
Create Order
import requests
url = "https://sandbox.boxme.asia/api/v1/courier/pricing/create_order"
payload = {
"ship_from": {
"country": "TH",
"pickup_id":1133
},
"ship_to": {
"contact_name": "Duong An",
"address": "Thailand,Pom Prap Sattru Phai,Bangkok",
"phone": "09356565",
"country": "TH",
"province": 190,
"district": 3353,
"subdistrict": 3353,
"zipcode": "10100"
},
"shipments": {
"content": "t-shirt, shoes",
"total_parcel": 1,
"total_amount": 120,
"chargeable_weight": 1000,
"description": "Please pick it up on 13:00",
"parcels": [
{
"dimension": {
"width": 0,
"height": 0,
"length": 0
},
"weight": 1000,
"description": "Please pick it up on 13:00",
"items": [
{
"sku": "SKU001",
"label_code": "",
"origin_country": "VN",
"name": "t-shirt",
"desciption": "",
"weight": 1000,
"amount": 200,
"quantity": 1
}
]
}
]
},
"config": {
"order_type": "fulfill",
"insurance": "N",
"document": "Y",
"currency": "THB",
"unit_metric": "metric",
"unique_order_number":"N"
},
"payment": {
"fee_paid_by": "sender",
"cod_amount": 0
},
"referral": {
"order_number": "XX-XX-XX"
}
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v1/courier/pricing/create_order"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {
"tracking_number": "BM81262653033",
"cod_value": 0,
"fee": {
"shipping_fee": 12000,
"cod_fee": 0,
"insurance_fee": 0,
"checking_fee": 0
}
},
"error": false,
"error_code": "",
"messages": "Create order successfully.",
"total": 0
}
Please check balance before create orders, you can not create orders if your balance not enought. For fulfillment order, we auto process and you can not cancel it after cutoff time.
HTTP Request
POST https://sandbox.boxme.asia/api/v1/courier/pricing/create_order
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
ship_from |
object | yes | Pickup address details. |
country |
string | yes | Shipper Country code (ISO 2-char country code). |
pickup_id |
integer | yes | ID of pickup address, must add country above. |
ship_to |
object | yes | Consignee address details. |
contact_name |
string | yes | Consignee name. |
company_name |
string | no | Consignee company name. |
address |
string | yes | Consignee address line 1. |
phone |
string | yes | Consignee Phone number. Accepted special characters are : - ( ) # + .. |
country |
string | yes | Consignee Country code (ISO 2-char country code) |
province |
integer | yes | Consignee state or province id. Refer to Location |
district |
integer | no | Consignee district id. Refer to to Location Only required for Viet Nam customers |
zipcode |
string | yes | Consignee zipcode. |
shipments |
object | yes | Shipments details. |
content |
string | yes | Parcel key content. |
total_parcel |
integer | yes | Total parcel of shipments. |
total_amount |
decimal | yes | Total shipments amount. |
description |
string | no | Note for shipments or driver. |
chargeable_weight |
decimal | yes | Chargeabe weight (lbs, gram). |
parcels |
list | yes | Parcel list |
config |
object | yes | Config informations. |
create_by |
string | no | Staff ID ( referal your CRM system) |
delivery_service |
string | no | Shipping service code |
sort_mode |
string | no | Sort by : best_price (default), best_time , best_rating |
order_type |
string | yes | Order type : normal (default), cross_border , consolidate , fulfill |
insurance |
string | no | Total shipments amount. Only accept Y or N |
currency |
string | yes | 3-char ISO currency code for all monetary value fields. |
unit_metric |
string | no | metric or imperial , default is metric |
unique_order_number |
string | no | Y or N , default is N . We check unique within 10days, default we checked phone number within 3mins ( all rules excluded orders cancelled) |
payment |
object | yes | Payment informations. |
fee_paid_by |
string | yes | Default fee paid by sender , if you change to receiver then we will add fee to CoD amount. |
cod_amount |
decimal | yes | Total CoD Amount(in 2 decimal points). We will calculate depend by fee_paid_by Formula: CoD Amount = cod_amount + total_fee (if fee_paid_by is receiver ). |
referral |
object | yes | Referral informations. |
order_number |
string | no | Your order number ( exp: shopify order_id) |
tracking_number |
string | no | Boxme tracking number (provide by Boxme) |
parcels
object.
Parameter | Data Type | Required | Description |
---|---|---|---|
weight |
string | yes | Parcel weight. |
description |
string | yes | Parcel description. |
items |
list | yes | List items of parcel. |
items
object.
Parameter | Data Type | Required | Description |
---|---|---|---|
sku |
string | no | Item SKU, require for fulfillment orders. |
origin_country |
string | no | Manufacture country . |
name |
string | yes | Item name. |
description |
string | yes | Product description. |
weight |
integer | no | Item weight. |
amount |
decimal | no | Item value ( per item). |
quantity |
integer | yes | Total quanity. |
Create exchange order
import requests
url = "https://sandbox.boxme.asia/api/v1/orders/create-order-return/<origin_tracking_number>"
payload = {
"pickup_id" : 341740,
"description" : "// return reason ",
"reason_code" : "OTHER",
"items" : [
{
"description" : "// return reason ",
"quantity" : 1,
"sku" : "8809625241353"
},
{
"description" : "// return reason ",
"quantity" : 1,
"sku" : "8809625241353"
}
]
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v1/orders/create-order-return/<origin_tracking_number>"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"messages": "",
"data": {
"new_tracking_number": "BM123123123"
},
"error": false,
"total": 0,
"error_code": ""
}
Create return order
HTTP Request
POST https://sandbox.boxme.asia/api/v1/orders/create-order-return/<origin_tracking_number>
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
pickup_id |
integer | yes | Boxme warehouse ID |
description |
string | yes | Note from customer, marketplace. |
reason_code |
string | yes | OTHER , WRONG_ITEM , ITEM_DAMAGED , ITEM_FAKE , ITEM_MISSING |
items |
list | yes | List exchange items will return to Boxme |
Request Response
Parameter | Data Type | Required | Description |
---|---|---|---|
new_tracking_number |
string | yes | New return tracking number |
Shipping Label
import requests
url = "http://sandbox.boxme.asia/api/v1/orders/generate-awb-label/ "
payload = {
"list_tracking": ["BM8104221956","BM8509833018"]
"page_size": "A5"
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
hádws
curl "http://sandbox.boxme.asia/api/v1/orders/generate-awb-label/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"messages": "",
"data": {
"label_url": "http://sandbox.boxme.asia/orders/awb-label/MjFmZjliMmUtOWFkOS00MTgzLTk3ZjYtNGUyOTg5YTJiZGY2"
},
"error": false,
"total": 0,
"error_code": ""
}
Get AWB label
HTTP Request
POST http://sandbox.boxme.asia/api/v1/orders/generate-awb-label/
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
list_tracking |
list | yes | List tracking number. Max: 20 tracking |
page_size |
list | yes | Paper size . A5 or A4 |
Request Response
Parameter | Data Type | Required | Description |
---|---|---|---|
label_url |
string | yes | AWB label url (PDF) |
Cancel Order
You can cancel the order before our warehouse ships out this shipment to the courier.
import requests
url = "http://sandbox.boxme.asia/api/v1/orders/cancel/BM8509833018/"
payload = {
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "http://sandbox.boxme.asia/api/v1/orders/cancel/BM8509833018/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {},
"error": false,
"error_code": "",
"messages": "Success",
"total": 0
}
HTTP Request
POST http://sandbox.boxme.asia/api/v1/orders/cancel/{tracking_number}
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
tracking_number |
string | yes | Tracking number need to cancel |
Request Response
Parameter | Data Type | Required | Description |
---|
Approve Order
import requests
url = "http://sandbox.boxme.asia/api/v1/orders/approve/BM8509833018/"
payload = {
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "http://sandbox.boxme.asia/api/v1/orders/approve/BM8509833018/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {},
"error": false,
"error_code": "",
"messages": "Update tracking number: BM8509833018 is success",
"total": 0
}
HTTP Request
POST http://sandbox.boxme.asia/api/v1/orders/approve/{tracking_number}
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
tracking_number |
string | yes | Tracking number need to approve |
Request Response
Parameter | Data Type | Required | Description |
---|
Return Order
import requests
url = "http://sandbox.boxme.asia/api/v1/courier/intergrate/confirm_return_tracking_code"
payload = {
"tracking_code" : "BM1234567890",
"note" : "Reason for return order"
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "http://sandbox.boxme.asia/api/v1/courier/intergrate/confirm_return_tracking_code"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {},
"error": false,
"error_code": "",
"messages": "Success",
"total": 0
}
HTTP Request
POST http://sandbox.boxme.asia/api/v1/courier/intergrate/confirm_return_tracking_code
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
tracking_code |
string | yes | Tracking number need to return |
note |
string | yes | Reason for return |
Request Response
Parameter | Data Type | Required | Description |
---|
Reshipping Order
import requests
url = "http://sandbox.boxme.asia/api/v1/courier/intergrate/confirm_delivery_tracking_code"
payload = {
"tracking_code" : "BM1234567890",
"note" : "Reason for reshipping order"
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "http://sandbox.boxme.asia/api/v1/courier/intergrate/confirm_delivery_tracking_code"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {},
"error": false,
"error_code": "",
"messages": "Success",
"total": 0
}
HTTP Request
POST http://sandbox.boxme.asia/api/v1/courier/intergrate/confirm_delivery_tracking_code
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
tracking_code |
string | yes | Tracking number need to reshipping |
note |
string | yes | Reason for reshipping |
Request Response
Parameter | Data Type | Required | Description |
---|
Get Order Fail Delivery
import requests
url = "https://sandbox.boxme.asia/api/v1/orders/rma/list/"
payload = {
'page': 1
'page_size': 50,
'create_from': 1560099600
'create_to': 1562778000
response = requests.request("GET", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v1/orders/rma/list/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {
"count": 2,
"next": "",
"previous": "",
"results": [
{
"rma_id": 264862,
"country": "VN",
"rma_number": "RMA676970803",
"tracking_number": "BM82203301707",
"task_id": 0,
"rma_type": 1,
"seller_info": {
"seller_id": 236216,
"email": "[email protected]",
"user_name": "Vũ Ngọc Hải",
"address": "",
"phone": "0984689451"
},
"order_info": {
},
"status": 100,
"status_name": "Chờ xử lý",
"status_name_en": "Opening",
"status_icon": "icon-clock",
"status_color": "badge badge-primary",
"return": {
},
"receiver_info": {
},
"quantity": 1,
"actual_quantity": 1,
"created_time": 1562726943,
"updated_time": 1562726943,
"lead_time": 1562899743,
"returned_time": 1562899743,
"successed_time": 0,
"rma_note": "kh hủy",
"rma_note_customer": "",
"accepted_time": 0
}
]
},
"error": false,
"error_code": "",
"messages": "",
"total": 2
}
HTTP Request
GET https://sandbox.boxme.asia/api/v1/orders/rma/list/
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
key |
string | no | Tracking number that you and to search |
create_from |
int | no | Filter list delivery failed by created time |
create_to |
int | no | Filter list delivery failed by created time |
page |
string | yes | Number of page |
page_size |
string | yes | Total item show in one page |
Request Response
Parameter | Data Type | Description |
---|---|---|
rma_number |
string | Number of RMA |
tracking_number |
string | Boxme tracking number |
rma_note |
string | Reason of fail delivery |
order_info.courier_name |
string | Courier's name |
order_info.courier_tracking_code |
string | Courier's tracking number |
order_info.weight |
int | Total order weight |
order_info.over_weight |
int | Over weight |
order.info.amount |
float | Total order amount |
order.info.money_collect |
float | Total CoD amount |
order.info.status |
int | Order status |
order.info.status_name_en |
string | Order status name in english |
order.info.status_name |
string | Order status name in local |
Get Tracking Status
import requests
url = "https://sandbox.boxme.asia/api/v1/orders/info/{tracking_number}/"
payload = {}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v1/orders/info/{tracking_number}/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": {
"order_number": "93821085",
"courier_tracking_code": "S1245828.SGE1.9V.P.481895224",
"tracking_number": "BM81632968566",
"weight": 500,
"service": {
"code": "GHTK_CPN",
"name": "Express service"
},
"status": "701",
"status_name_local": "Đơn hủy bởi vận hành",
"status_name": "Cancelled by operator",
"courier": [
{
"prefix": "gtk",
"name": "Giao Hàng Tiết Kiệm",
"url_track": "http://khachhang.giaohangtietkiem.vn/khach-hang/tracking/order/"
}
],
"receiver": {
"country": "VN",
"fullname": "Arthit Kamon",
"zipcode": "",
"province": "TP. Hồ Chí Minh",
"district": "Quận 5"
},
"journey": [
{
"status": "201",
"status_name_local": "HVC đang lấy hàng",
"status_name": "Picking",
"city_name": "Boxme",
"note": "",
"created_time": "03-04-2020 11:07:46"
},
{
"status": "200",
"status_name_local": "Đã duyệt",
"status_name": "Verified",
"city_name": "Boxme",
"note": "Order created",
"created_time": "03-04-2020 11:07:44"
}
]
},
"error": false,
"error_code": "",
"messages": "",
"request_id": 1587219100,
"total": 0
}
You can get tracking status by this API but we recommend to use our webhook to get real-time tracking status
HTTP Request
POST https://sandbox.boxme.asia/api/v1/orders/info/{tracking_number}/
Request Response
Parameter | Data Type | Description |
---|---|---|
order_number |
string | Number Your order number ( exp: shopify order_id) |
courier_tracking_code |
string | Courier's tracking number |
tracking_number |
string | Tracking number (Boxme) |
weight |
int | Total order weight |
service.code |
string | Shipping service code |
service.name |
int | Shipping service name |
status |
int | Order status |
status_name_local |
string | Status name local |
status_name |
string | Status name (EN) |
courier.prefix |
string | Courier prefix |
courier.name |
string | Courier name |
url_track |
string | Link to track status of order from courie |
receiver.country |
string | Consignee Country code (ISO 2-char country code) |
receiver.fullname |
string | Consignee name |
receiver.zipcode |
string | Consignee zipcode. |
receiver.province |
string | Consignee province |
receiver.district |
string | Consignee district |
journey |
array | Journey of orders Journey |
Journey detail
Parameter | Data Type | Required | Description |
---|---|---|---|
status |
int | Order status | |
status_name_local |
string | Status name local | |
status_name |
string | Status name (EN) | |
city_name |
string | Location of orders at the time | |
note |
string | Note | |
created_time |
string | Time |
Init Fulfillment
import requests
url = "https://sandbox.boxme.asia/api/v2/orders/init_fulfillment/{tracking_number}/"
payload = {
"courier_name": "Rồng Thiêng",
"courier_tracking_code": "TH123123",
"label": "",
"label_type": "PDF"
}
headers = {
'content-type': "application/json",
'authorization': "api key",
}
response = requests.request("POST", url, data=payload, headers=headers)
curl "https://sandbox.boxme.asia/api/v2/orders/init_fulfillment/BM814648137833/"
-H "Authorization: api key"
The above command returns JSON structured like this:
{
"data": null,
"error": false,
"error_code": "",
"messages": "Init Fulfillment successfully.",
"total": 0
}
This API init fulfillment for orders which are self-delivery or synced from ecommerce platfrom such as: Lazada, Tiki, Shopee, Sendo...
HTTP Request
POST https://sandbox.boxme.asia/api/v2/orders/init_fulfillment/{tracking_number}/
Request Body
Parameter | Data Type | Required | Description |
---|---|---|---|
courier_name |
string | yes | Name of Courier |
courier_tracking_code |
string | yes | After pushing orders to courier successfully, courier with return courier_tracking_code for tracking delivery of order |
label |
string | no | Data is base64 encoded |
label_type |
string | no | Type of label. Value is "PDF" or "PNG" |
Webhook
Receive a webhook
A webhook is a tool for retrieving and storing data from certain events. Boxme sends webhooks when status changes in the lifespan of an Order. This documentation covers the core resources needed to receive webhooks from Boxme.
Note: Go to Settings page > Intergration > Webhook API to config webhook
We will issue a HTTP POST request to the URL specified every time an event occurs. The request's POST parameters will contain JSON data relevant to the event that triggered the request
Receive Order Status
Please refer sample JSON in right side.
A sample JSON of a hook Boxme sends:
{
"data": {
"data_raw": {
"TrackingCode": "BM813319360550",
"CourierTrackingCode": "EB546078019VN",
"Fee": [
{
"FeeCode": "handling_fee",
"FeeValue": 2160,
"Currency": "VND"
}
],
"OrderCode": "EB546078019VN",
"Weight": 555,
"StatusCode": 502,
"StatusName": "Received",
"Location": "Boxme_VN",
"Note": "",
"ListItem": [
{
"Sku": "SP8708873306",
"Quantity": 1,
"ProductName": "Senka Perfect Aqua Bouncy Mask #Bouncy Bright (VN) (HCT)",
"SerialNumbers": null
},
{
"Sku": "thucamontgsf",
"Quantity": 1,
"ProductName": "Thư cảm ơn TGSF",
"SerialNumbers": null
},
{
"Sku": "5011451103931",
"Quantity": 1,
"ProductName": "Simple Hydrating Light Moisturiser 125ml - kem dưỡng ẩm (VN)",
"SerialNumbers": null
},
{
"Sku": "8809348604428",
"Quantity": 1,
"ProductName": "Foodaholic Derma Brightening Mask With Vitamin C (1 miếng lẻ) (VN)",
"SerialNumbers": null
},
{
"Sku": "4901872455249",
"Quantity": 1,
"ProductName": "Senka Perfect UV Essence 50g (VN)",
"SerialNumbers": null
},
{
"Sku": "5011451103856",
"Quantity": 1,
"ProductName": "Simple Kind To Skin Soothing Facial Toner 200ml (mẫu xanh mới) (VN)",
"SerialNumbers": null
},
{
"Sku": "SP8708874566",
"Quantity": 1,
"ProductName": "Găng Tay Tẩy Da Chết Body Scrubber Glove #Hồng Đậm (VN) (HCT)",
"SerialNumbers": null
}
],
"ListReturnedItems": [],
"ReturnsInformation": {
"OriginTrackingCode": "BM808835251947",
"ReturnStatus": 2,
"ReturnStatusName": "Received",
"ListImage": []
},
"AdditionalInfos": {},
"OrderType": "return_parcel",
"TimeStamp": 1649055992
}
}
}
Parameter | Data Type | Description |
---|---|---|
TrackingNumber |
string | Boxme tracking code. |
CourierTrackingNumber |
string | Courier tracking code (maybe same like Boxme tracking code). |
OrderCode |
string | Your order number. |
Fee |
list | Return correct fee when orders have final status. |
ListItem |
list | Return the list of packed items. |
ReturnsInformation.OriginTrackingCode |
string | Origin tracking code. |
ReturnsInformation.ReturnStatus |
number | Return status (2: Received at our warehouse, 4: Completed inspect and putaway returned order). |
OrderType |
string | normal : normal order, exchange : exchange order return_parcel : failed delivery order |
Weight |
decimal | Order weight (gram). |
StatusCode |
string | Order status code, please refer List Order Status. |
StatusName |
string | Order status name, please refer List Order Status. |
Location |
string | Order Location. |
TimeStamp
| string | Status updated time
Use can go to Webhook test page send a test event.
Order Status Event
Status Code | Status Name | Detail |
---|---|---|
200 | Verified | Order have been approved |
201 | Picking | |
202 | Pickup failed | |
203 | On the way to drop-off | |
210 | Processing at warehouse | |
211 | Ready to ship at warehouse | |
212 | Out of stock | |
220 | Awaiting to sourcing | |
230 | Cross border processing | |
231 | Received at origin facility | |
232 | Departed at origin facility | |
233 | Cross border transit | |
235 | Customs cleared | |
234 | Customs onhold | |
236 | Received at desitination facility | |
237 | Departed at desitination facility | |
300 | Shipped | |
310 | Out for delivery | |
400 | Out of delivery | |
410 | Awaiting to return | |
420 | Return processing | |
430 | Return approved | |
500 | Returning | |
510 | Out of return | |
511 | Return refused | |
520 | Awaiting receive at facility | |
530 | Return to orgin facility | |
610 | Returned at orgin facility | |
600 | Returned | Return to your warehouse or Boxme warehouse (Final) |
605 | Destroy at destination | Parcels destroy at destination hub (Final) |
700 | Cancelled by sellers | |
701 | Cancelled by operator | |
702 | Cancelled by partner | |
703 | Cancelled by system | |
704 | Pending for audit | Operator need check and verify next status of order |
705 | Cancel at warehouse | Order cancelled after pick & pack (final) |
800 | Delivered | Delivery successfull (Final) |
801 | Fulfilled | Order fulfilled and ship to your courier(final) |
Receive inventory event
Please refer sample JSON in right side.
A sample JSON of a hook Boxme sends:
{
"bsin": "BSN123456789",
"seller_sku": "SKU0001",
"weight": 100,
"volume": "15x10x5",
"time_create": 1593497728,
"country": "VN",
"ff_center_code": "BMVN_HCM",
"quantity_in_stock": 100,
"waiting_outbound": 5,
"damaged_in_stock": 0
}
Parameter | Data Type | Description |
---|---|---|
bsin |
string | Bsin. |
seller_sku |
string | Product SKU. |
weight |
number | Actual weight by gram |
volume |
string | Product dimensions (LxWxH) |
time_create |
number | Event updated time (TimeStamp) |
country |
string | Country store this product. |
ff_center_code |
string | OrderFulfillment code of BOXME |
quantity_in_stock |
number | Total number items Available. |
inventory |
number | Total number items stocking. |
waiting_outbound |
number | Total number items waiting pickup. |
damaged_in_stock |
number | Total number items damage. |
Receive Shipment Status
Please refer sample JSON in right side.
A sample JSON of a hook Boxme sends:
{
"shipment_code" : "SM-VN-123-123456",
"tracking_number" : "OV2058901823",
"is_unloaded": false,
"status": 6,
"list_products" : [
{
"seller_sku" : "SKU-123456",
"quantity_damaged" : 0,
"quantity_received" : 20,
"barcode" : "1010101010",
"weight_packed" : 200,
"volume" : "40x30x20",
"list_serial_number" : [ ],
"box_no" : "#1001",
"quantity_barcode" : 20
},
{
"seller_sku" : "SKU-222222",
"quantity_damaged" : 0,
"quantity_received" : 10,
"barcode" : "1010101011",
"weight" : 200,
"volume" : "40x30x20",
"list_serial_number" : [ ],
"box_no" : "#1001",
"quantity_barcode" : 0
}
]
}
Parameter | Data Type | Description |
---|---|---|
shipment_code |
string | Boxme shipment code. |
tracking_number |
string | Delivery tracking number or customer reference. |
is_unloaded |
boolean | True : Boxme unloaded (containers, ...). |
status |
int | Shipment status code, please refer List Shipment Status. |
status_nane |
string | Shipment status name, please refer List Shipment Status. |
list_products |
string | Shipment status name, please refer List Shipment Products. |
Shipment Product Detail
Parameter | Data Type | Description |
---|---|---|
sku |
string | Your product SKU. |
quantity_received |
number | Quantity received in warehouse |
quantity_damaged |
number | Quantity damaged in warehouse |
barcode |
number | Your product barcode. |
weight |
number | weight at warehouse (gram) |
volume |
string | volume at warehouse |
list_serial_number |
string | list serial number |
box_no |
string | Box code |
quantity_barcode |
string | Number of labels |
Shipment Status Event
Status Code | Status Name | Detail |
---|---|---|
1 | New | Shipment created waiting for approval |
2 | Approved Shipment | Shipment approved |
4 | Processing at warehouse | Processing at warehouse |
5 | Cancelled by sellers | Shipment cancelled by sellers |
6 | Success | Shipment success |
7 | Cancelled by operator | Shipment cancelled by operator Boxme |
8 | Out of stock | Shipment (outbound) out of stock |
Webhook testing
You can use for testing & check authentication
Errors
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- Your API key is wrong.. |
404 | Not Found -- API 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 api requested has been removed from our servers. |
418 | I'm a teapot. |
429 | Too Many Requests -- You're requesting too many api ! 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. |