POST batch create - Submit Orders

URL: /api/order-batch/create　·　Description: Submit multiple orders at once; returns the batch ID and validation summary.

Asynchronous: the endpoint returns immediately with a batch ID and the orders are processed asynchronously. Use detail to query the progress and results (poll until the batch status is “Completed”). A failure of a single order does not affect the other orders in the same batch.

Shipping address (choose one): the batch shipping address has two ways to pass, pick either one:
① Pass vendor_address_id (a saved address, same as the “Upload Excel” batch feature);
② Pass the shipper_* sender fields directly (see the “Sender fields” table below), where shipper_name / shipper_street1 / shipper_country / shipper_state / shipper_city are required.
Passing neither returns a parameter error.

Note: when creating a batch via Upload Excel, only vendor_address_id is supported; shipper_* fields are NOT accepted. The shipper_* fields apply only to this endpoint (API array submission).

Parameters

Parameter	Required	Type	Description
`vendor_address_id`	Either	int	Shipping address ID (uniformly used for the whole batch); *choose one with the `shipper_` below** (if omitted, the shipper_* fields are required)
`orders`	Yes	array	Array of orders (JSON array body, or a JSON string in a form field); element fields are listed below
`shipping_code`	Yes	string	Batch channel code (required); must be filled together with shipping_service; applies to all orders in the batch
`shipping_service`	Yes	string	Batch service code (required); filled as a pair with shipping_code; applies to all orders in the batch
`remark`	Optional	string	Batch remark

Sender fields shipper_* (choose one with vendor_address_id)

Batch sender information. If vendor_address_id is omitted, pass the fields below; shipper_name / shipper_street1 / shipper_country are required (the rest are optional). They act as a “temporary” sender address that applies only to this batch.

Parameter	Required	Type	Description
`shipper_name`	Either-required	string	Sender name (required when vendor_address_id is omitted)
`shipper_company`	Optional	string	Sender company
`shipper_telphone`	Optional	string	Contact phone
`shipper_email`	Optional	string	Email
`shipper_country`	Either-required	string	Country (e.g. `US`; required when vendor_address_id is omitted)
`shipper_state`	Either-required	string	State / province (required when vendor_address_id is omitted)
`shipper_city`	Either-required	string	City (required when vendor_address_id is omitted)
`shipper_street1`	Either-required	string	Sender address line 1 (required when vendor_address_id is omitted)
`shipper_street2`	Optional	string	Sender address line 2
`shipper_zipcode`	Optional	string	Zip code

orders[] Element Fields

Parameter	Required	Type	Description
`recipient_name`	Yes	string	Recipient name
`recipient_street1`	Yes	string	Recipient address line 1
`recipient_city`	Yes	string	Recipient city
`recipient_state`	Yes	string	Recipient state / province
`recipient_country`	Yes	string	Recipient country (two-letter code, e.g. `US`)
`weight` / `length` / `width` / `height`	Yes	number	Weight and dimensions, all must be greater than 0
`reference`	Optional	string	Order reference number
`recipient_company`	Optional	string	Recipient company
`recipient_street2`	Optional	string	Recipient address line 2
`recipient_telphone`	Optional	string	Recipient phone
`recipient_zipcode`	Optional	string	Recipient zip code
`package_name`	Optional	string	Package name
`weight_unit`	Optional	string	Weight unit: `kg` / `g` / `lb` / `oz`, default `lb`
`length_unit`	Optional	string	Dimension unit: `cm` / `m` / `in`, default `in`
`ship_date`	Optional	string	Ship date
`is_signature`	Optional	int	Signature required; `1`/`yes` is treated as yes, anything else as no
`is_insurances`	Optional	int	Insurance required; `1`/`yes` is treated as yes, anything else as no
`remark`	Optional	string	Order remark

Note: shipping_code and shipping_service must always appear as a pair — the channel is set at the batch level and applies to all orders in the batch; they must be filled together; filling only one of them returns a parameter error.

Request Example

POST /api/order-batch/create
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "vendor_address_id": 12,
    "shipping_code": "iusps",
    "shipping_service": "zdgj",
    "remark": "batch 20260921",
    "orders": [
        {
            "reference": "ORDER-20260921-001",
            "recipient_name": "Jane",
            "recipient_street1": "456 Oak Ave",
            "recipient_city": "New York",
            "recipient_state": "NY",
            "recipient_country": "US",
            "recipient_zipcode": "10001",
            "weight": 3.3,
            "length": 12,
            "width": 10,
            "height": 5,
            "weight_unit": "lb",
            "length_unit": "in"
        }
    ]
}

Request Example ② (pass shipper_* directly, without vendor_address_id)

POST /api/order-batch/create
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "shipping_code": "iusps",
    "shipping_service": "zdgj",
    "remark": "batch 20260921-shipper",
    "shipper_name": "John Doe",
    "shipper_company": "ACME Co.",
    "shipper_telphone": "+1 213 555 0100",
    "shipper_country": "US",
    "shipper_state": "CA",
    "shipper_city": "Los Angeles",
    "shipper_street1": "123 Main St",
    "shipper_street2": "Suite 200",
    "shipper_zipcode": "90001",
    "orders": [
        {
            "reference": "ORDER-20260921-001",
            "recipient_name": "Jane",
            "recipient_street1": "456 Oak Ave",
            "recipient_city": "New York",
            "recipient_state": "NY",
            "recipient_country": "US",
            "recipient_zipcode": "10001",
            "weight": 3.3,
            "length": 12,
            "width": 10,
            "height": 5,
            "weight_unit": "lb",
            "length_unit": "in"
        }
    ]
}

Response Example

{
    "success": true,
    "message": "Batch submitted, processing asynchronously. Poll detail by batch_id.",
    "code": 200,
    "data": {
        "batch_id": 88,
        "batch_no": "B20260921153000ab12",
        "total_count": 2,
        "success_count": 1,
        "fail_count": 1
    }
}

data field	Type	Description
`batch_id`	int	Batch ID, used by `detail` to query the processing results
`batch_no`	string	Batch number
`total_count`	int	Total number of submitted orders
`success_count`	int	Number of orders that passed validation and entered processing
`fail_count`	int	Number of orders that failed validation (reasons are shown in `detail`)

API Documentation 📘 中文版