POST /2026-05/cloud/label/manifests

Method: POST

URL: https://openapi.zhenhub.com/2026-05/cloud/label/manifests

Sandbox URL: https://openapi.test.zhenhub.cn/2026-05/cloud/label/manifests

Description: Creates a shipping manifest or replaces the complete contents of an existing manifest with the same reference.

Choose how parcels are grouped

Provide boxes, top-level parcels, or both. At least one label_id is required across the complete request. Use boxes for packed parcels and top-level parcels for parcels that are not packed in a box.

Parameters

Parameter	Description	Type
reference	Your unique manifest reference. Leading and trailing spaces are ignored. Maximum length: 64.	String, Required
boxes	Boxes included in the manifest. Omit when all parcels are unpacked.	Array
boxes[].reference	Your box reference. It must be unique within the manifest. Maximum length: 64.	String, Required
boxes[].parcels	Parcels packed in this box. Each box must contain at least one parcel.	Array, Required
boxes[].parcels[].label_id	Label ID returned by the Create Shipping Label API.	Long, Required
parcels	Parcels included directly in the manifest and not packed in a box.	Array
parcels[].label_id	Label ID returned by the Create Shipping Label API.	Long, Required
metadata	Optional customer-defined data associated with the manifest.	Object

Body

{
  "reference": "BATCH-20260907-001",
  "boxes": [
    {
      "reference": "BOX-001",
      "parcels": [
        { "label_id": 100001 },
        { "label_id": 100002 }
      ]
    },
    {
      "reference": "BOX-002",
      "parcels": [
        { "label_id": 100003 }
      ]
    }
  ],
  "parcels": [
    { "label_id": 100004 }
  ],
  "metadata": {
    "warehouse": "HK01"
  }
}

Response

{
  "code": 200,
  "message": "OK – The request was successful.",
  "data": {
    "reference": "BATCH-20260907-001",
    "box_count": 2,
    "parcel_count": 4
  }
}

The response confirms your manifest reference and the saved counts. box_count and parcel_count are calculated by the server from the saved Box and Parcel relationships.

Replacement behaviour

The manifest reference identifies the manifest within your company and API environment.

• If the reference does not exist, a new manifest is created.
• If the reference already exists, its Boxes, Parcels, and metadata are replaced by this request.
• Each request is a complete snapshot. Include parcels from earlier requests when they must remain in the manifest.
• Array order does not affect the saved manifest.
• If a Label currently belongs to a different manifest, it is moved to the manifest in the latest successfully processed request. The previous manifest counts are recalculated.
• Concurrent requests are applied atomically. The last successfully committed request determines the saved contents.

Send the complete manifest

Do not send only newly arrived parcels when replacing a manifest. Any Box or Parcel omitted from the request is removed from that manifest.

Validation and errors

• Every label_id must identify an existing shipping label owned by your company in the current API environment.
• Cancelled Labels and Labels that are not eligible for manifesting are rejected.
• Each Box must contain at least one Parcel.
• Each label_id must appear only once in the request.
• Empty manifests and duplicate Box references are rejected.
• Validation is completed before replacement. A failed request does not partially change an existing manifest.
• 400 indicates an invalid request structure or field value.
• 404 indicates that a supplied Label does not exist in the current company and environment.
• 409 indicates that one or more Labels cannot currently be manifested because of their shipment status.

Notes

• This endpoint records the relationship between a Manifest, its optional Boxes, and shipping Labels.
• It does not create a carrier close-out, generate a carrier manifest file, or dispatch the shipment.
• Production and Sandbox manifests are isolated. A Label created in one environment cannot be used in the other.
• Use the returned Label id as label_id; carrier tracking numbers are not accepted.