Create order B2B

Developing

POST

/api/v1/public/orders/create

Last modified:2025-04-04 10:42:16

This API is used to create a new B2B order. The order includes details about the buyer, receiver, products, shipping method, pickup address, and optionally the vendor.
It supports conditional logic such as using customer_id to auto-fill receiver info, or manual input if customer_id is not provided.

Request

Header Params

Authorization

string

optional

Default:

6pGkII/faXeTxkNR1wOXRKZniSG25HgtPoDr3dLcuAcegBUKinCDkkdpxeSULdtPE0I7P8nM7dWTPRUyhzgtvQ==

Body Params application/json

store_id

string

required

pickup_id

string

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

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

This must be filled if customer_id is null

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: "b2b" (business-to-business).

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.

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.

tax_paid_by

string

required

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

fee_paid_by

string

required

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

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.).

extra_info

object

required

note

string | null

optional

packaging_note

string | null

optional

order_number

string

required

estimated_departure_time

integer | null

optional

documents

array [object {4}]

optional

name

string

optional

Name of the document (can be dynamically generated).

quantity

integer

optional

Number of copies or instances of the document.

doc_type

string

optional

Specifies the type of document related to the order or transaction.
1: Purchase order (A formal document issued to request a purchase)
2: Invoice (A billing document for the transaction.)
99: Other (Any other document type that does not fall into the predefined categories.)

url

string

optional

URL link to access the document (e.g., Google Drive, internal storage, etc.).

Example

{
  "store_id": "{{store_id_b2b}}",
  "pickup_id": "{{pickup_id}}",
  "receiver": {
    "customer_id": null,
    "country": "VN",
    "fullname": "{{$person.fullName(locale='vi')}}",
    "phone": "{{$phone.number(locale='vi')}}",
    "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": 0
    }
  ],
  "discounts": [],
  "fees": [
    {
      "code": "buyer_shipping_fee",
      "amount": 31000
    }
  ],
  "items": [
    {
      "sku": "250204067",
      "sale_price": 30700000,
      "discounted_price": 30700000,
      "quantity": 10
    }
  ],
  "config": {
    "order_type": "b2b",
    "approve": 1,
    "preview": 1,
    "use_insurance": 0,
    "fulfill_now": 0,
    "delivery_service": "SOF_STD",
    "additional_services": "CIG,OWH",
    "tax_paid_by": "sender",
    "fee_paid_by": "sender",
    "courier_integration_id": 172,
    "courier_id": 16
  },
  "extra_info": {
    "note": "Giao tới nhà có cổng màu tím trước sân cây hoa mai",
    "packaging_note": "Kiểm tra hàng trong sản phẩm còn nguyên vẹn trước khi đóng gói",
    "order_number": "{{$string.numeric(length=10,locale='vi')}}",
    "estimated_departure_time": {{$date.timestamp|addDays(3)}}
  },
  "documents": [
    {
      "name": "{{$food.dish}}",
      "quantity": 2,
      "doc_type": "3",
      "url": "google.com"
    }
  ]
}

Request samples

Shell

JavaScript

Java

Swift

Go

PHP

Python

HTTP

C

C#

Objective-C

Ruby

OCaml

Dart

R

curl --location --request POST 'https://stg-oms.nandh.vn/api/v1/public/orders/create' \
--header 'Authorization: 6pGkII/faXeTxkNR1wOXRKZniSG25HgtPoDr3dLcuAcegBUKinCDkkdpxeSULdtPE0I7P8nM7dWTPRUyhzgtvQ==' \
--header 'Content-Type: application/json' \
--data-raw '{
  "store_id": "{{store_id_b2b}}",
  "pickup_id": "{{pickup_id}}",
  "receiver": {
    "customer_id": null,
    "country": "VN",
    "fullname": "{{$person.fullName(locale='\''vi'\'')}}",
    "phone": "{{$phone.number(locale='\''vi'\'')}}",
    "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": 0
    }
  ],
  "discounts": [],
  "fees": [
    {
      "code": "buyer_shipping_fee",
      "amount": 31000
    }
  ],
  "items": [
    {
      "sku": "250204067",
      "sale_price": 30700000,
      "discounted_price": 30700000,
      "quantity": 10
    }
  ],
  "config": {
    "order_type": "b2b",
    "approve": 1,
    "preview": 1,
    "use_insurance": 0,
    "fulfill_now": 0,
    "delivery_service": "SOF_STD",
    "additional_services": "CIG,OWH",
    "tax_paid_by": "sender",
    "fee_paid_by": "sender",
    "courier_integration_id": 172,
    "courier_id": 16
  },
  "extra_info": {
    "note": "Giao tới nhà có cổng màu tím trước sân cây hoa mai",
    "packaging_note": "Kiểm tra hàng trong sản phẩm còn nguyên vẹn trước khi đóng gói",
    "order_number": "{{$string.numeric(length=10,locale='\''vi'\'')}}",
    "estimated_departure_time": {{$date.timestamp|addDays(3)}}
  },
  "documents": [
    {
      "name": "{{$food.dish}}",
      "quantity": 2,
      "doc_type": "3",
      "url": "google.com"
    }
  ]
}'

Responses

🟢200OK

application/json

Body

status_code

integer

optional

data

object

optional

order_id

integer

optional

tracking_code

string

optional

error

boolean

optional

error_code

null

optional

log_id

null

optional

messages

string

optional

total

integer

optional

Example

{
  "status_code": 0,
  "data": {
    "order_id": 0,
    "tracking_code": "string"
  },
  "error": true,
  "error_code": null,
  "log_id": null,
  "messages": "string",
  "total": 0
}

Modified at 2025-04-04 10:42:16

Create order B2C