Order API

---

Create an order

Method	POST
URL	/api/order/create-order

Request body

{
  "address_id": 2,
  "consignee_name": "sarenda mcguire",
  "consignee_phone": "",
  "consignee_address": "6105 W Elmwood Dr",
  "consignee_address_other": "",
  "consignee_country": "US",
  "consignee_city": "Wildomar",
  "consignee_postal_code": "57718",
  "consignee_state_code": "SD",
  "order_number": "DEV123456789",
  "product_name": "Metal",
  "product_price": 5.5,
  "length": 1.93,
  "width": 108,
  "height": 1.9,
  "weight": 1.1,
  "service_code": "EPK",
  "service_add": "",
  "money_collection": 0,
  "order_code_upstream_partner": "partner_of_partner",
  "package_option": "818",
  "unit_type": "cm-g",
  "label_sender": "WRIGLEYS Cool Air",
  "mode": null
}

Field reference

No.	Field Name	Data Type	Description
1	address_id	Long	Warehouse ID (see Reference API)
2	consignee_name	String	Recipient full name
3	consignee_phone	String	Recipient phone number
4	consignee_address	String	Recipient address line 1
5	consignee_address_other	String	Recipient address line 2
6	consignee_country	String	Country code (fixed: US)
7	consignee_city	String	City / province (see Reference API)
8	consignee_postal_code	String	5 digits (entered by the user)
9	consignee_state_code	String	State code (see Reference API)
10	order_number	String	Partner's order number
11	product_name	String	Description of goods
12	product_price	Decimal	Value of goods
13	length	Decimal	Length (cm)
14	width	Decimal	Width (cm)
15	height	Decimal	Height (cm)
16	weight	Decimal	Weight (grams)
17	service_code	String	Main service (contact Bell for the list)
18	service_add	String	Value-added services
19	money_collection	Decimal	Cash on delivery amount
20	order_code_upstream_partner	String	Order code of your own upstream partner
21	package_option	String	Lithium battery: 818 (Marked), 820 (Unmarked). For service LBE6 use the full code: 8181, 8182, 8201, 8202. Leave empty if there is no battery
22	unit_type	String	Unit for dimensions and weight. Defaults to cm-g when omitted (mm-g, cm-g, cm-kg, in-lb)
23	label_sender	String	Sender agent name printed on the label. If not set, the label_sender configured on your customer account is used
24	mode	String	Pass "advanced" to use Advanced Mode (see below). Leave empty or null for Simple Mode

Validation Rules

info

Contact Bell to get the list of available service_code values. The service must exist in the BELL system.

address_id

• Required, integer.
• Each service only accepts specific address_id values (provided by Bell on request).

order_number

• Required, up to 50 characters.
• Must be unique per customer (must not repeat an order number you have already used).
• For services US_UPS_GROUND and US_UNIUNI_D: only the characters a-z A-Z 0-9 _ ( ) - , # space are allowed.

consignee_name

• Required, up to 100 characters.
• For service US_UPS_GROUND: must contain the full first and last name (at least 2 words separated by a space).

consignee_phone

• Optional.
• If provided, must be exactly 10 digits (e.g. 0123456789).

consignee_email

• Optional.
• If provided, must be a valid email address, up to 50 characters.

consignee_country

• Required, 2-letter country code (ISO-2).

consignee_state_code

• Required when consignee_country = US.
• Optional for other countries.
• Up to 50 characters.

consignee_postal_code

• Required, up to 20 characters.
• Format depends on the country:
  • US: 5 digits or 5+4 (e.g. 57718 or 57718-1234).
  • GB/UK: Royal Mail format (e.g. SW1A 1AA).
• For services US_UNIUNI and US_UNIUNI_D: the postal code must be within UniUni's service area.

consignee_address

• Required, up to 200 characters.

consignee_address_other

• Optional, up to 200 characters.

unit_type

• Optional. Default: cm-g.
• Allowed values: mm-g, cm-g, cm-kg, in-lb.

length / width / height

• Required, numeric value > 0.
• Maximum: 150 cm (converted according to unit_type).

weight

• Required, numeric value > 0.

product_name

• Optional, up to 100 characters.

product_price

• Optional, numeric value ≥ 0.

service_add

• Optional, up to 100 characters.

label_sender

• Optional, up to 50 characters.
• If not set, the label_sender configured on your customer account is used.

package_option (Lithium Battery)

• Optional.
• Only allowed with services EPK, LBE, LBE6.
• Allowed values per service:

Service	Allowed values	Description
EPK, LBE	818, 820	818 = Marked, 820 = Unmarked
LBE6	8181, 8182, 8201, 8202	Full code: 818x = Marked, 820x = Unmarked

• When package_option is set, packages must meet these limits:

Service	Maximum weight	Length + 2×Width + 2×Height
EPK	≤ 11 lbs	< 108 inch
LBE	≤ 11 lbs	< 108 inch
LBE6	≤ 11 lbs	< 108 inch

info

If the goods contain batteries, set package_option to the code that matches the service,

and attach the mark https://express.bellvn.com/UN-3091.jpg or https://express.bellvn.com/UN-3481.jpg

Response

{
  "error": false,
  "ref": null,
  "message": "Tạo đơn thành công",
  "data": "DEV123456789",
  "warnings": []
}

Field reference

No.	Field Name	Data Type	Description
1	error	boolean	Error flag
2	ref	String	Transaction reference code
3	message	String	Message
4	data	String	BELL order code
5	warnings	Array	Warnings listing fields the system automatically converted to ASCII (services US_UNIUNI_D, US_UPS_GROUND, LBE6)

Each item in warnings:

Field	Description
field	Name of the converted field
label	Display name of the field
original	Original value before conversion
sanitized	Value after conversion to ASCII
message	Description of the automatic action

---

Create an order (Advanced Mode)

For international services that require detailed customs declarations and support multiple packages (multi-package).

Method	POST
URL	/api/order/create-order

Note

The following services must use advanced mode:

• UPS_WW_SAVER2, UPS_WW_SAVER
• UPS_WW_EXPEDITED2, UPS_WW_EXPEDITED
• UPS_WW_EXPRESS2, UPS_WW_EXPRESS
• FEDEX_IPE2, FEDEX_IPE, FEDEX_IP2, FEDEX_IP
• FEDEX_IE2, FEDEX_IE, FEDEX_ICP2, FEDEX_ICP
• FEDEX_IP_SBP, FEDEX_IP_SBP2

If you use one of these services without mode: "advanced" or without goods information, the request fails validation.

ASCII Auto-Sanitize

For services US_UNIUNI_D, US_UPS_GROUND, LBE6: the system automatically converts accented Vietnamese characters to ASCII (e.g. á → a, đ → d) in name and address fields. The response includes a warnings array listing the converted fields.

Request body

{
  "mode": "advanced",
  "address_id": 0,
  "service_code": "UPS_WW_EXPRESS",
  "order_number": "PARTNER-ADV-001",
  "order_code_upstream_partner": "UPSTREAM-001",
  "consignee_name": "John Doe",
  "consignee_company": "ACME Corp",
  "consignee_phone": "2125550001",
  "consignee_email": "john@example.com",
  "consignee_country": "US",
  "consignee_state_code": "NY",
  "consignee_city": "New York",
  "consignee_postal_code": "10001",
  "consignee_address": "123 Main Street",
  "consignee_address_other": "Suite 100",
  "unit_type": "cm-g",
  "package_option": null,
  "label_sender": "MY STORE",
  "service_add": "",
  "packages": [
    {
      "weight": 1000,
      "length": 30,
      "width": 20,
      "height": 15,
      "goods": [
        {
          "name_en": "Electronic Device",
          "name_vi": "Thiết bị điện tử",
          "brand": "BrandName",
          "packaging_type": "Box",
          "origin": "CN",
          "price": 150.00,
          "quantity": 2,
          "unit": "pcs",
          "hs_code": "8471.30",
          "material": "Plastic"
        }
      ]
    },
    {
      "weight": 500,
      "length": 25,
      "width": 18,
      "height": 10,
      "goods": [
        {
          "name_en": "Accessories",
          "name_vi": "Phụ kiện",
          "brand": null,
          "packaging_type": null,
          "origin": "VN",
          "price": 25.50,
          "quantity": 5,
          "unit": "pcs",
          "hs_code": null,
          "material": null
        }
      ]
    }
  ],
  "extra_fields": {
    "trade_terms": "DDP",
    "tax_type": "IOSS",
    "tax_number": "IOSS-123456789",
    "signature_required": true
  }
}

Simple vs Advanced

Feature	Simple (default)	Advanced
Number of packages	1 package (pass length, width, height, weight directly)	Multiple packages (packages array)
Goods declaration	product_name + product_price	Detailed goods array (name, origin, HS code, ...)
Supported services	All domestic services	Required for international services (UPS WW, FedEx IP)
Extra fields	No	Supports trade_terms, tax_type, tax_number

Additional fields

No.	Field Name	Data Type	Description
1	mode	String	Required for advanced services. Value: "advanced"
2	consignee_company	String	Recipient company name. Required for advanced services, up to 100 characters
3	consignee_email	String	Recipient email. Optional, up to 50 characters
4	packages	Array	Array of packages. Required, at least 1 package
5	packages[].weight	Decimal	Package weight (per unit_type, grams by default)
6	packages[].length	Decimal	Length (per unit_type, cm by default)
7	packages[].width	Decimal	Width (per unit_type, cm by default)
8	packages[].height	Decimal	Height (per unit_type, cm by default)
9	packages[].goods	Array	Goods in this package. Required, at least 1 item
10	packages[].goods[].name_en	String	Goods name (English). Required, up to 100 characters
11	packages[].goods[].name_vi	String	Goods name (Vietnamese). Optional
12	packages[].goods[].brand	String	Brand. Optional
13	packages[].goods[].packaging_type	String	Packaging type. Optional
14	packages[].goods[].origin	String	Country of origin code (ISO-2). Required, 2 characters
15	packages[].goods[].price	Decimal	Goods value (USD). Required, minimum 0.01
16	packages[].goods[].quantity	Integer	Quantity. Required, minimum 1
17	packages[].goods[].unit	String	Unit of measure (e.g. pcs, kg, set). Optional
18	packages[].goods[].hs_code	String	Customs HS code. Optional
19	packages[].goods[].material	String	Material. Optional
20	extra_fields	Object	Additional tax / trade information. Optional
21	extra_fields.trade_terms	String	Trade terms: DDU, DDP, CIP, C&F. For FEDEX_ICP/FEDEX_ICP2 only DDP is allowed
22	extra_fields.tax_type	String	Tax type: IOSS, EORI, VAT
23	extra_fields.tax_number	String	Corresponding tax number (up to 100 characters)
24	extra_fields.signature_required	Boolean	Signature required on delivery. JingDong services only, Advanced Mode only

Advanced Mode validation

packages

• Required, array with at least 1 item.
• Each package must include weight, length, width, height.
• Values must be > 0. Maximum dimension 150 cm (converted according to unit_type).

goods (for services that require advanced mode)

• Required, array with at least 1 item.
• Each goods item must include:
  • name_en: required, up to 100 characters
  • origin: required, 2 characters (ISO-2 country code)
  • price: required, number > 0 (minimum 0.01)
  • quantity: required, integer ≥ 1

extra_fields

• Optional.
• If provided, every value inside must be a string or a boolean.

extra_fields.trade_terms

• Allowed values: DDU, DDP, CIP, C&F.
• For services FEDEX_ICP and FEDEX_ICP2: only DDP is accepted.

extra_fields.tax_type

• Allowed values: IOSS, EORI, VAT.

extra_fields.signature_required

• Type boolean. Only supported by JingDong services.
• Only allowed in Advanced Mode; rejected (prohibited) if sent in Simple Mode.

Unit conversion

The system stores values internally in mm-g. When you send a different unit_type, values are converted automatically:

unit_type	Weight → grams	Dimensions → mm
mm-g	×1	×1
cm-g	×1	×10
cm-kg	×1000	×10
in-lb	×453.59	×25.4

Response

Same as the standard create order response:

{
  "error": false,
  "ref": null,
  "message": "Tạo đơn thành công",
  "data": "BELL240625120345123"
}

Validation error example

{
  "error": true,
  "ref": null,
  "message": "Service này yêu cầu mode \"advanced\" với đầy đủ thông tin goods.",
  "errors": {
    "goods.0.origin": ["origin là bắt buộc"],
    "goods.0.price": ["price là bắt buộc"]
  },
  "data": null
}

---

Edit the address of a failed order and resubmit

For orders in the Error status (status = 11) that the carrier rejected because of the recipient address. The API saves the new address and puts the order back into the resubmission flow, keeping the same BELL order code — no new order is created.

The request is asynchronous: BELL returns 202 as soon as the address has been saved and queued, and only then calls the carrier. Get the final result by looking up the order (see Track the result).

Method	POST
URL	/api/order/edit-order

Recommended flow

1. Call /api/order/get-order-info/{id} to read status and processing_error, so you know exactly which field to fix.
2. Call /api/order/edit-order with the address fields to change.
3. A 202 means the request has been queued. Call /api/order/get-order-info/{id} again to get the final result.
4. On error, handle it based on the code in the error response (see the result code table).

Request body

{
  "order_code": "BELL240625120345123",
  "consignee_country": "US",
  "consignee_state_code": "CA",
  "consignee_city": "San Francisco",
  "consignee_postal_code": "94105",
  "consignee_address": "123 Main Street",
  "consignee_address_other": "Suite 200"
}

Field reference

No.	Field Name	Data Type	Description
1	order_code	String	Required. BELL waybill code (order_code), up to 100 characters. Do not use your own order number or the carrier's code
2	consignee_country	String	Country code (ISO-2), up to 2 characters
3	consignee_state_code	String	State code, up to 50 characters. Required for US and for advanced services
4	consignee_city	String	City / province, up to 50 characters
5	consignee_postal_code	String	Postal code, up to 20 characters. Must follow the country / UniUni rules in Validation Rules
6	consignee_address	String	Recipient address line 1, up to 200 characters
7	consignee_address_other	String	Recipient address line 2, up to 200 characters. Send null to clear it

Editing rules

• You must send at least one address field. Sending only order_code is rejected with VALIDATION_FAILED.
• Address fields you do not send keep their current value. Sending the same value as before still counts as a resubmission request.
• Only the 6 address fields above are allowed. Any other key (address_id, service_code, status, consignee_name, consignee_phone, packages, goods, extra_fields, amount fields...) is rejected, even if sent as null.
• The warehouse, BELL order code, service, packages and goods cannot be changed. To change them, cancel the order and create a new one.
• The new address is validated against the rules of the service attached to the order. consignee_country is normalized to upper case and UK → GB.
• For services that require ASCII (US_UNIUNI_D, US_UPS_GROUND, LBE6), the submitted address is converted to ASCII automatically and the response includes the corresponding warnings array.

Order eligibility

The order must meet all of the following conditions, otherwise you receive 409:

• It belongs to the customer calling the API (a different owner returns 404, indistinguishable from an order that does not exist).
• It is in the Error status (status = 11) and has not been deleted.
• It has no carrier order code and no tracking yet.
• No resubmission is currently in progress for it.

warning

Do not import, edit or cancel the order from the web interface while a resubmission is running. Each order is processed one attempt at a time.

Success response (202)

Short envelope, same as the create order API:

{
  "error": false,
  "ref": null,
  "message": "Cập nhật đơn thành công",
  "data": "BELL240625120345123",
  "warnings": []
}

Field reference

No.	Field Name	Data Type	Description
1	error	boolean	false = BELL has received and recorded the request
2	ref	String	Always null in a success response
3	message	String	Cập nhật đơn thành công ("Order updated successfully")
4	data	String	BELL waybill code (unchanged by the edit)
5	warnings	Array	Non-blocking warnings, e.g. ASCII auto-sanitize. Same structure as the create order API

202 does not mean the carrier has accepted the order

202 only confirms that the new address has been saved and the order has been queued for resubmission. The call to the carrier happens after the response is returned. You must look up the final result separately — see Track the result.

Processing flow

Synchronous (before the response is returned):

1. Check ownership and order eligibility.
2. Validate the new address against the rules of the service attached to the order.
3. Verify the address with the address validation provider (can take up to ~25 seconds).
4. Estimate the shipping charge for the new address — reads the price list only, nothing is posted to your account balance.
5. Save the new address and the carrier payload. The order moves from Error (11) to Init (1).
6. Return 202.

Asynchronous (after the response is returned):

7. BELL calls the carrier to create the shipment and records the result.
8. If accepted: the charge is updated, the label is downloaded and the order moves to Label (3).
9. If rejected: the order goes back to Error (11) and processing_error is updated with the new reason.

Track the result

Call /api/order/get-order-info/{id} and read status:

status	Meaning
Init	Being sent to the carrier. Wait and check again
Label	Resubmitted successfully. tracking_code and tracking_label_url are now populated
Error	The carrier rejected the order. Read processing_error for the reason, fix it and call the API again

tip

This usually takes from a few seconds to a few tens of seconds. Wait 5–10 seconds before the first check, and limit the number of polls. If the order stays in Init for too long (more than a few minutes), contact support with the order code instead of calling the API again — a repeated call will be blocked with 409.

Result codes

Success is always 202 with the short envelope above. Every code below is an error that happens before the address is saved. Error envelopes include an extra code field — always handle errors by code, not by message.

HTTP	code	Meaning and what to do
404	ORDER_NOT_FOUND	Order not found or it does not belong to your account. data = null
409	ORDER_BUSY	The order is being processed by another process. Try again later
409	ORDER_NOT_EDITABLE	The order is not in the Error status, or already has a carrier order code / tracking
409	RECOVERY_NOT_RETRYABLE	No valid recovery attempts remain for this order
409	PROVIDER_RESULT_UNKNOWN	A resubmission is already in progress or its result is unknown. Do not call again — wait or contact support with the ref
409	BILLING_LOCKED	The invoice has been closed or the account balance needs review. Contact support
409	ADDRESS_RECOMMENDATION_AVAILABLE	A corrected address is suggested. Review suggestions, confirm, then call again
422	VALIDATION_FAILED	Invalid payload or address. See errors
422	ADDRESS_VALIDATION_FAILED	The address could not be verified
422	PRICING_UNAVAILABLE	A shipping charge could not be calculated for the new address
422	UNSUPPORTED_PROVIDER	The order's carrier configuration does not support this flow
503	PROVIDER_UNAVAILABLE	The carrier request could not be prepared. Nothing was sent; you can try again
503	ADDRESS_VALIDATION_UNAVAILABLE	The address validation service is temporarily unavailable. Try again later
503	LOCAL_PERSISTENCE_FAILED	BELL could not process the request. If the response has a non-null ref, do not call again — look up the order status first

Example: field that cannot be edited (422)

{
  "error": true,
  "ref": null,
  "code": "VALIDATION_FAILED",
  "message": "This field cannot be edited.",
  "data": null,
  "errors": {
    "consignee_name": ["This field cannot be edited."]
  },
  "warnings": []
}

Example: suggested address (409)

{
  "error": true,
  "ref": null,
  "code": "ADDRESS_RECOMMENDATION_AVAILABLE",
  "message": "Địa chỉ có đề xuất cần xác nhận trước khi tiếp tục.",
  "data": null,
  "suggestions": {
    "consignee_city": "San Francisco",
    "consignee_postal_code": "94105-1804"
  },
  "warnings": []
}

suggestions uses the partner field names and is never applied automatically — confirm the values, then call the API again with the values you want.

Charges and payment

• The preflight charge estimate only reads the price list and wallet limit. It creates no transaction, holds no funds and posts no charge.
• The charge is updated only after the carrier accepts the order, i.e. after the 202 response has been returned. Receiving 202 does not mean the charge has changed.
• Look up the new charge with /api/price/get-price/{order_number} after the order reaches Label. Before that, the returned value is still the charge for the old address.
• If the carrier rejects the order, the charge stays as it was before the edit.
• This flow creates no new order, package, goods or payment transaction.

Timeouts and retries

Do not retry automatically

The API no longer waits for the carrier, but it still performs a synchronous address validation step that can take up to ~25 seconds. Set your HTTP timeout to at least 60 seconds.

If the request times out or fails on your side because of a network error, do not call again immediately — the address may already have been saved and the order queued for resubmission. Call /api/order/get-order-info/{id} to check the actual status before doing anything else.

Situation	Can you call again?
202 success	No. The order is being resubmitted — track the result
VALIDATION_FAILED, ADDRESS_VALIDATION_FAILED	Yes, after fixing the data
ADDRESS_RECOMMENDATION_AVAILABLE	Yes, after confirming the suggestion
ORDER_BUSY, PROVIDER_UNAVAILABLE, ADDRESS_VALIDATION_UNAVAILABLE	Yes, wait a few minutes and try again
PROVIDER_RESULT_UNKNOWN, LOCAL_PERSISTENCE_FAILED with a ref	No. Look up the order status and contact support with the ref
Timeout / no response received	No. Call get-order-info first
Order returns to Error with a new processing_error	Yes, fix the address based on the reason and call again

---

Cancel an order

Method	POST
URL	/api/order/cancel-order

Request payload

No.	Field Name	Data Type	Description
1	order_number	String	BELL waybill code

Response

{
  "error": false,
  "ref": null,
  "message": "Thành công",
  "data": null
}

---

Print a shipping label

Method	GET
URL	/api/order/print-order/{order_number}

Path parameter

No.	Field Name	Data Type	Description
1	order_number	String	BELL waybill code or your own order number (order_code_partner)

Response

{
  "error": false,
  "ref": null,
  "message": "Thành công",
  "data": {
    "orderNumber": "BELL1202103548",
    "tracking": "42080521921449037400250000264",
    "labelFormat": "PDF",
    "labelSize": "4x6",
    "label": "",
    "labelUrl": "https://storage.bellvn.com/labels/BELL1202103548.pdf",
    "receiptUrls": [
      "https://storage.bellvn.com/receipts/BELL1202103548_1.pdf"
    ],
    "trackings": [
      {
        "tracking_code": "42080521921449037400250000264",
        "package_no": 1
      }
    ],
    "processing_error": null
  }
}

Field reference

No.	Field Name	Data Type	Description
1	error	boolean	Error flag
2	ref	String	Reference code
3	message	String	Message
4	data.orderNumber	String	Order code that was queried
5	data.tracking	String	Main tracking number of the order
6	data.labelFormat	String	Label file format: PDF, GIF, PNG, JPG (or empty if there is no label yet)
7	data.labelSize	String	Label size (default 4x6)
8	data.label	String	Base64 label content (currently always empty — use labelUrl instead)
9	data.labelUrl	String	URL of the label file to download or view online
10	data.receiptUrls	Array	URLs of waybill receipt files. May be empty []
11	data.trackings	Array	Tracking numbers per package (multi-package). Empty [] for single-package orders or when there is no tracking yet
12	data.processing_error	String	Reason the order failed (status = 11 Error), explained in Vietnamese. null if the order is not in an error state

info

receiptUrls and trackings only have values for JingDong service orders (multi-package orders or orders with their own receipts). For other services, both fields are empty arrays.

---

Look up order information

Method	GET
URL	/api/order/get-order-info/{id}

Path parameter

No.	Field Name	Data Type	Description
1	id	String	BELL order code (order_code), your own order number (order_code_partner), or internal ID (id)

Response

{
  "status": "success",
  "message": "Get order info successfully",
  "data": {
    "order_code": "BELL240625120345123",
    "order_code_partner": "DEV123456789",
    "status": "Label",
    "service": "EPK",
    "reason": null,
    "processing_error": null,
    "tracking_code": "42080521921449037400250000264",
    "tracking_label_url": "https://storage.bellvn.com/labels/BELL240625120345123.pdf",
    "carrier": "USPS",
    "ship_date": "2024-06-25",
    "consignee_name": "sarenda mcguire",
    "consignee_phone": "0123456789",
    "consignee_company": null,
    "consignee_country": "US",
    "consignee_state": "SD",
    "consignee_city": "Wildomar",
    "consignee_postal_code": "57718",
    "consignee_address": "6105 W Elmwood Dr",
    "consignee_address2": null,
    "created_date": "2024-06-25 12:03:45"
  }
}

Response fields

No.	Field Name	Data Type	Description
1	status	String	success or error
2	message	String	Result message
3	data.order_code	String	BELL waybill code
4	data.order_code_partner	String	Your own order number
5	data.status	String	Order status (see the table below)
6	data.service	String	Service code
7	data.reason	String	Reason (e.g. cancellation reason). Null if none
8	data.processing_error	String	Reason the order failed (status = Error), explained in Vietnamese by BELL. null if the order is not in an error state or the cause could not be determined
9	data.tracking_code	String	Carrier tracking number
10	data.tracking_label_url	String	URL of the label file
11	data.carrier	String	Carrier name
12	data.ship_date	String	Ship date
13	data.consignee_name	String	Recipient name
14	data.consignee_phone	String	Recipient phone number
15	data.consignee_company	String	Recipient company
16	data.consignee_country	String	Country code (ISO-2)
17	data.consignee_state	String	State / province
18	data.consignee_city	String	City
19	data.consignee_postal_code	String	Postal code
20	data.consignee_address	String	Recipient address
21	data.consignee_address2	String	Recipient address line 2
22	data.created_date	String	Order creation time

Order statuses

Value	Description
Init	Newly created
Label	Label generated
In Transit	In transit
Out For Delivery	Out for delivery
Delivered	Delivered
Exception	Exception occurred
Void	Cancelled
Request Cancel	Cancellation requested
Unknown	Unknown
Draft	Draft

Common errors

{
  "status": "error",
  "message": "Order not found"
}

{
  "status": "error",
  "message": "Order not belong to Customer"
}

---

Track shipment

Method	GET
URL	/api/order/tracking/{order_number}

Path parameter

No.	Field Name	Data Type	Description
1	order_number	String	BELL waybill code

Response

{
  "error": false,
  "ref": null,
  "message": "Thành công",
  "data": [
    {
      "trackingNumber": "BELL2512171654532484",
      "code": "12345678900",
      "city": "City 0",
      "stateCode": "State 0",
      "zipCode": "Zip 0",
      "countryCode": "Country 0",
      "eventDate": "2025-12-18T03:57:04.896549Z",
      "eventStatus": "LabelCreated 0",
      "note": "Label Created"
    },
    {
      "trackingNumber": "BELL2512171654532484",
      "code": "12345678901",
      "city": "City 1",
      "stateCode": "State 1",
      "zipCode": "Zip 1",
      "countryCode": "Country 1",
      "eventDate": "2025-12-18T03:57:04.896558Z",
      "eventStatus": "LabelCreated 1",
      "note": "Label Created"
    }
  ]
}

Field reference

No.	Field Name	Data Type	Description
1	error	boolean	Error flag (false = success)
2	ref	String	Request reference code (may be null)
3	message	String	Result message
4	data	Array	List of tracking events
5	data[].trackingNumber	String	Waybill / tracking number
6	data[].code	String	Event code or internal reference code
7	data[].city	String	City where the event occurred
8	data[].stateCode	String	State / province code
9	data[].zipCode	String	Postal code
10	data[].countryCode	String	Country code (ISO-2)
11	data[].eventDate	String	Time of the event (ISO 8601, UTC)
12	data[].eventStatus	String	Tracking event status / content
13	data[].note	String	Status note / description

---

Look up order charges

Method	GET
URL	/api/price/get-price/{order_number}

Path parameter

No.	Field Name	Data Type	Description
1	order_number	String	BELL waybill code

Response

{
  "error": false,
  "message": "Success",
  "data": [
    {
      "order_code": "BELL2512171654532484",
      "amount": 15.50,
      "type": "MAIN"
    }
  ]
}

Field reference

No.	Field Name	Data Type	Description
1	error	boolean	Error flag (false = success)
2	message	String	Result message
3	data	Array	Charge breakdown
4	data[].order_code	String	Waybill code
5	data[].amount	Decimal	Charge amount
6	data[].type	String	Charge type (MAIN: main shipping charge, or another surcharge)

info

The API only returns charges for orders in an active invoice. If the order has not been charged yet or has no invoice, an error is returned.