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

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

Wehook test page

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.