Create order B2C

POST

/api/v1/public/orders/create

This API is used to create a B2C (Business-to-Consumer) order on the N&H OMS system. It includes customer, payment, shipping, product, and courier details. The API supports options like insurance, fulfillment settings, and courier selection.
It supports conditional logic such as using customer_id to auto-fill receiver info, or manual input if customer_id is not provided.

Sample Use Case

Creating a B2C order where:

2 SKUs are being ordered

The payment is cash-on-delivery (COD)

A shipping fee is applied

The order is auto-approved and previewed

The seller chooses self-fulfillment using a defined courier

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/api/v1/public/orders/create' \
--header 'Authorization;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "store_id": 336,
    "pickup_id": 167,
    "receiver": {
        "customer_id": null,
        "country": "VN",
        "fullname": "{% faker name.fullName %}",
        "phone": "+84961557476",
        "address": "Số 9 Trà Khúc",
        "zipcode": "77000",
        "province_name": "TP. Hồ Chí Minh",
        "district_name": "Tân Bình",
        "ward_name": "Phường 2"
    },
    "payments": [
        {
            "status": 100,
            "method": 1,
            "amount": 100000
        }
    ],
    "fees": [
        {
            "code": "buyer_shipping_fee",
            "amount": 31000
        }
    ],
    "items": [
        {
            "sku": "BANHTRANGXIKI",
            "sale_price": 25000,
            "discounted_price": 30000,
            "quantity": 2
        },
        {
            "sku": "MUOIXATAC",
            "sale_price": 15000,
            "discounted_price": 20000,
            "quantity": 2
        }
    ],
    "config": {
        "order_type": "b2c",
        "approve": 1,
        "preview": 1,
        "use_insurance": 0,
        "fulfill_now": 0,
        "delivery_service": "SOF_STD",
        "box_dimension": 120,
        "courier_integration_id": 212,
        "courier_id": 16
    },
    "extra_info": {
        "note": "Giao trong ngày",
        "packaging_note": "Giao trong ngày",
        "order_number": "{% faker datatype.number %}"
    }
}'

Response Example

{
  "status_code": 200,
  "data": {
    "order_id": 11733,
    "tracking_code": "NHOV851691511"
  },
  "error": false,
  "error_code": null,
  "log_id": null,
  "messages": "",
  "total": 1
}

Request

Header Params

Authorization

string

required

Default:

Body Params application/json

store_id

integer

required

pickup_id

integer

required

receiver

object

required

To implement the logic where the customer_id field determines whether the other fields are mandatory or not, you can structure it as follows:
API Request Logic:
If customer_id is provided: Other fields such as fullname, phone, address, zipcode, province_name, district_name, and ward_name are optional.
If customer_id is null: Other fields (fullname, phone, address, zipcode, province_name, district_name, ward_name) are mandatory.

customer_id

integer | null

optional

If customer_id is null, the following fields are required

country

string

optional

This must be filled if customer_id is null

fullname

string

optional

This must be filled if customer_id is null

phone

string

optional

This must be filled if customer_id is null

address

string

optional

This must be filled if customer_id is null

zipcode

string

optional

province_name

string

optional

This must be filled if customer_id is null

district_name

string

optional

This must be filled if customer_id is null

ward_name

string

optional

This must be filled if customer_id is null

payments

array [object {3}]

required

Required: ✅ Yes – Must contain at least one object.
Purpose: Records payment method, payment status, and amount paid or to be paid for the order.

status

integer

required

Value Meaning
100 Not paid
110 Payment in process
120 Awaiting payment
150 Partially paid
200 Paid
250 Awaiting refund
300 Refunded
310 Partially refunded
500 Payment cancelled
550 COD collection cancelled
600 Overdue

method

integer

required

Value Method
1 COD (Cash on Delivery)
2 Bank Transfer
3 Visa/Master/Amex Card
4 Cash
5 QR Code
6 Online Banking
7 Installment Payment

amount

integer

required

A portion has already been paid via bank transfer (1,000,000 VND – status: 200)
The remaining amount is unpaid and will be collected via COD (500,000 VND – status: 100)

fees

array [object {2}]

optional

code

string

optional

🔹buyer_shipping_fee
Meaning: Shipping fee paid by the buyer after discounts.
This is the final shipping cost charged to the buyer, after any shipping discounts have been applied.
📝 Example:
If the original shipping fee is 30,000 VND and there's a platform discount of 10,000 VND, then:
→ buyer_shipping_fee = 20,000
🔹 total_platform_discount
Meaning: Total discount provided by the platform.
This includes all promotions, coupons, or automatic discounts that the platform applies to the order, including product discounts or shipping fee subsidies.
📝 Example:
If the platform gives:
15,000 VND off on products
10,000 VND off shipping
→ total_platform_discount = 25,000

amount

integer

optional

items

array [object {4}]

required

sku

string

required

Stock Keeping Unit – A unique identifier for the product in inventory.

sale_price

integer

required

Original sale price of a single item, before any discount (in VND).

discounted_price

integer

required

Price after discount per unit (in VND).

quantity

integer

required

Number of items being purchased in this order.

config

object

required

order_type

string

required

Type of order. Example: "b2c"

approve

integer

required

1 = Automatically approve the order after creation.

preview

integer

required

1 = Request a preview before finalizing the shipment (usually used for fee estimation).

use_insurance

integer

required

1 = Enable shipment insurance, 0 = Do not use insurance.

fulfill_now

integer

required

fulfill_now
Type: integer
Purpose: Controls whether the order is fulfilled immediately after creation.
Meaning:
1 = Express fulfillment – the order is processed immediately after it's created (used for urgent or priority handling).
0 = Do not fulfill immediately – the order is saved but needs to be manually fulfilled later.
📝 Use case: Set fulfill_now: 1 for rush or same-day orders that need to be shipped out as soon as possible.

delivery_service

string

required

Code of the shipping/delivery service to use. Example: "SOF_STD" for standard service.

tax_paid_by

string | null

optional

Party responsible for tax. "sender" or "receiver".

fee_paid_by

string | null

optional

Party responsible for shipping fees. "sender" or "receiver".

box_dimension

integer

required

Kích thước kiện tính phí

courier_integration_id

integer

required

ID of the courier integration (e.g. integrated shipping provider account).

courier_id

integer

required

ID of the shipping carrier (e.g. GHN, GHTK, VNPost, etc.).

additional_services

string | null

optional

Comma-separated list of extra services.
CIG: Package inspection upon pickup
OWH: Delivery outside working hours
IGD: Package inspection upon delivery
Example: "CIG,OWH" → Enable both package inspection at pickup and out-of-hours delivery.

extra_info

object | null

optional

note

string | null

optional

packaging_note

string | null

optional

order_number

string | null

optional

Examples

Responses

🟢200OK

application/json

Body

status_code

integer

required

data

object

required

order_id

integer

required

tracking_code

string

required

error

boolean

required

error_code

null

optional

log_id

null

optional

messages

string

required

total

integer

required

List shipping service of courier

Create order B2B

Create order B2C

Sample Use Case#

Request

Responses

Sample Use Case