> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/package-management/resources/tutorials/creating-a-package.md). # Creating a Package This tutorial shows how to create a package with Package Management API v1. ```http POST https://api.sandbox.esw.com/packagemanagement/v1/{tenantCode}/orders/{orderReference}/packages Authorization: Bearer Content-Type: application/json ``` *** ### Required fields The API requires `packageReference` and `weight`. The URL also requires your `tenantCode` and `orderReference`.
Required | Field | Type | Description | | ------------------ | ------ | --------------------------------------- | | `tenantCode` | string | Your ESW tenant code | | `orderReference` | string | The order that contains the package | | `packageReference` | string | Unique reference for this package | | `weight` | object | Package weight and its measurement unit |
`weight` requires both `weight` and `weightUnit`. ```json "weight": { "weight": 1.45, "weightUnit": "kg" } ``` *** ### Create a package Use `POST` to create a package. A successful request returns `201 Created`. {% code title="Create package request" lineNumbers="true" expandable="true" %} ```json { "packageReference": "PKG-2026-0001", "weight": { "weight": 1.45, "weightUnit": "kg" }, "shippingStatus": "Pending", "goodsDescription": "Apparel", "serviceLevel": "EXP2", "parentOrderReference": "ORD-2026-0001", "eswCarrierIdentifier": "CARRIER-001", "carrierReference": "CARRIER-PKG-2026-0001", "originFulfillmentCentreCode": "IEDUB", "shippingInfo": { "amount": 12.0, "currency": "EUR" }, "insuranceInfo": { "amount": 149.0, "currency": "EUR" }, "dangerousGoodsInfo": { "dangerousGoods": true, "dangerousGoodsClassificationCode": "4.1", "dangerousGoodsUnNumber": "UN0001", "dangerousGoodsContentId": "DG-001" }, "dimensionInfo": { "length": 35.0, "width": 15.0, "height": 25.0, "measurementUnit": "cm", "weight": { "weight": 1.45, "weightUnit": "kg" } }, "consigneeAddress": { "firstName": "Jane", "lastName": "Smith", "address1": "350 Fifth Avenue", "address2": "Suite 100", "address3": "Attn: Receiving", "city": "New York", "poBox": "123", "region": "NY", "postalCode": "10118", "countryIso": "US", "email": "jane.smith@example.com", "telephone": "+12125551234" }, "packageItems": [ { "productCode": "SKU-00789", "lineItemId": 1, "quantity": 1, "productDescription": "Silk scarf", "productCustomsDescription": "Woven silk scarf", "countryOfOriginIso": "FR", "hsCode": "6214.10", "weight": { "weight": 0.15, "weightUnit": "kg" }, "unitPriceInfo": { "amount": 149.0, "currency": "EUR" }, "dangerousGoods": true, "metaData": "{\"warehouseZone\":\"A1\"}" } ], "metaData": "{\"packingStation\":\"PS-01\"}" } ``` {% endcode %} ### Request fields All fields except `packageReference` and `weight` are optional. | Field | Type | Description | | ----------------------------- | ------ | -------------------------------------- | | `shippingStatus` | string | Package shipping status | | `goodsDescription` | string | Description of the packaged goods | | `serviceLevel` | enum | Delivery service level | | `parentOrderReference` | string | Reference for the related parent order | | `eswCarrierIdentifier` | string | Carrier identifier supplied by ESW | | `carrierReference` | string | Carrier's package reference | | `originFulfillmentCentreCode` | string | Origin fulfilment centre code | | `shippingInfo` | object | Shipping price | | `insuranceInfo` | object | Insurance price | | `dangerousGoodsInfo` | object | Dangerous-goods declaration | | `dimensionInfo` | object | Package dimensions | | `consigneeAddress` | object | Delivery recipient address | | `packageItems` | array | Items included in the package | | `metaData` | string | Additional JSON metadata | #### Service level and shipping status Use one of these values where applicable. | Field | Valid values | | ---------------- | ---------------------- | | `serviceLevel` | `POST`, `EXP2`, `PUDO` | | `shippingStatus` | `Complete`, `Pending` | #### Carrier information Provide carrier details when they are available. * `eswCarrierIdentifier` identifies the carrier in ESW. * `carrierReference` is the carrier's reference for this package. #### Price and weight `shippingInfo` and `insuranceInfo` share the same structure. Both properties require `amount` and `currency` when included. ```json "shippingInfo": { "amount": 12.0, "currency": "EUR" } ``` | Object | Required fields | Notes | | ----------------- | ---------------------- | -------------------------------------- | | `weight` | `weight`, `weightUnit` | Use a numeric value and its unit | | Price information | `amount`, `currency` | Use a numeric amount and currency code | #### Dimensions `dimensionInfo` requires `length`, `width`, `height`, and `measurementUnit`. It can also include `weight`. ```json "dimensionInfo": { "length": 35.0, "width": 15.0, "height": 25.0, "measurementUnit": "cm", "weight": { "weight": 1.45, "weightUnit": "kg" } } ``` #### Consignee address When you include `consigneeAddress`, provide every required property. | Required | Optional | | ------------------------------------------- | ------------------------------------------------------- | | `firstName`, `lastName`, `address1`, `city` | `address2`, `address3`, `poBox`, `region`, `postalCode` | | `countryIso`, `email`, `telephone` | — | `countryIso` uses a two-character ISO country code. #### Package items Each item requires `productCode` and `quantity`. | Field | Description | | --------------------------- | ------------------------------------- | | `lineItemId` | Optional integer line-item identifier | | `productDescription` | Product description | | `productCustomsDescription` | Customs description | | `countryOfOriginIso` | Product origin country code | | `weight` | Item weight | | `unitPriceInfo` | Price per item | | `dangerousGoods` | Dangerous-goods indicator | | `hsCode` | Harmonized System code | | `metaData` | Item metadata as a JSON string | #### Dangerous goods Use `dangerousGoodsInfo` to declare package-level dangerous goods. ```json "dangerousGoodsInfo": { "dangerousGoods": true, "dangerousGoodsClassificationCode": "4.1", "dangerousGoodsUnNumber": "UN0001", "dangerousGoodsContentId": "DG-001" } ``` ### Successful response The API returns `201 Created`. The body contains `outcome`, `status`, and `package`. ```json { "outcome": "PackageAndLabelCreated", "status": "Created", "package": { "tenantCode": "TENANT", "orderReference": "ORD-2026-0001", "packageReference": "PKG-2026-0001", "shippingStatus": "Pending" } } ``` `outcome` can be `PackageCreated`, `PackageAndLabelCreated`, or `PackageCreatedAndLabelError`. It can also return `PackageCreatedAndLabelOnHold`. The returned package can include `shippingDocumentation`. Each document reports its `type`, `format`, `link`, and `documentStatus`. | Field | Valid values | | ------------------ | ----------------------------------------------------------------------------------------- | | Documentation type | `HubHandlingLabel`, `ShippingLabel`, `SupportingDocumentation`, `AdditionalDocumentation` | | Document format | `Zpl`, `Pdf`, `NoLabel` | | Document status | `Created`, `Error` | ### HTTP Status Code | Status | Meaning | Action | | ------ | ------------------------------------ | ---------------------------------------------------- | | `400` | The payload is invalid | Check required fields and nested object requirements | | `401` | Authentication failed | Send a valid JWT in `Authorization: Bearer ` | | `403` | Access is denied | Confirm the client can access the tenant and order | | `404` | The tenant or order does not exist | Verify `tenantCode` and `orderReference` | | `409` | The package reference already exists | Use a unique `packageReference` for this order | | `500` | An unexpected error occurred | Record the response `traceId` and contact support | Error responses can include `type`, `title`, `status`, `detail`, `instance`, `traceId`, and field-level `errors`. {% hint style="warning" %} The API rejects additional properties. Send only fields defined by the request schema. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.esw.com/package-management/resources/tutorials/creating-a-package.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.