Version: 1.0.0
This document describes the internal data structures exchanged between your profiles and the CEP Connector profiles within the Lobster Data Platform.
Input data structure
Shipment booking
Pass the following LobsterCEP data structure to the CEP_CONNECTOR_ShipmentBooking profile. The connector maps it to the carrier's format, sends it to the carrier, and returns the result to your acknowledgement profile.
LobsterCEP
Root structure for CEP shipping operations.
Required fields: header, shipment
Field | Type | Required | Description |
|---|---|---|---|
header | Header | Yes | Contains carrier information, requested action, and document requirements. |
shipment | Shipment | Yes | Full shipment details, including parties, packages, and customs |
metaInformation | MetaInformation | No | Key-value metadata passed through the connector to be available in the response |
Example
{
"LobsterCEP": {
"header": {
"carrierId": "DHL_EXPRESS",
"action": "CREATE",
"requestedDocuments": [
"LABEL",
"COMMERCIAL_INVOICE"
]
},
"shipment": {
"shipmentId": "SHP12345678",
"shipperReference": "ORD-987654321",
"carrierReference": "CARRIER-REF-001",
"consigneeReference": "PO-12345",
"orderNumbers": {
"salesOrderNumbers": [
"SO-123456",
"SO-123457"
],
"purchaseOrderNumbers": [
"PO-87654",
"PO-87655"
]
},
"serviceType": "P",
"additionalServices": [
{
"serviceCode": "INSURANCE",
"serviceDescription": "Additional insurance coverage"
},
{
"serviceCode": "SIGNATURE_REQUIRED",
"serviceDescription": "Signature required on delivery"
}
],
"shippingDateTime": "2023-10-15T08:30:00.000Z",
"incoTerm": "DAP",
"incoTermLocation": "Destination Warehouse",
"movementType": "OUTBOUND",
"pickupRequestedFlag": true,
"dropOffFlag": false,
"accountNumber": {
"value": "123456789"
},
"paymentInformation": {
"transportation": {
"paymentType": "SENDER"
},
"dutiesAndTaxes": {
"paymentType": "RECEIVER",
"accountNumber": "987654321",
"countryCode": "DE"
}
},
"parties": {
"shipper": {
"addressIdentifiers": [
{
"identifierValue": "DE123456789",
"identifierType": "VAT"
},
{
"identifierValue": "DE987654321",
"identifierType": "EOR"
}
],
"reference": "SHIPPER-001",
"name1": "Global Trading GmbH",
"name2": "Logistics Department",
"name3": "Building A",
"street1": "Industriestrasse 45",
"street2": "Floor 3",
"zipcode": "10557",
"city": "Berlin",
"countryCode": "DE",
"countryName": "Germany",
"stateCode": "BE",
"stateName": "Berlin",
"contacts": [
{
"name": "Hans Schmidt",
"email": "hans.schmidt@globaltrading.de",
"phone": "+49 30 12345678",
"fax": "+49 30 12345679"
}
]
},
"recipient": {
"addressIdentifiers": [
{
"identifierValue": "FR12345678900",
"identifierType": "VAT"
}
],
"reference": "RECIPIENT-002",
"name1": "Tech Innovations SARL",
"name2": "Receiving Department",
"street1": "25 Rue de la Paix",
"street2": "Batiment C",
"zipcode": "75002",
"city": "Paris",
"countryCode": "FR",
"countryName": "France",
"contacts": [
{
"name": "Marie Dubois",
"email": "marie.dubois@techinnovations.fr",
"phone": "+33 1 23456789"
}
]
},
"importer": {
"name1": "Tech Innovations SARL",
"street1": "25 Rue de la Paix",
"zipcode": "75002",
"city": "Paris",
"countryCode": "FR"
},
"exporter": {
"name1": "Global Trading GmbH",
"street1": "Industriestrasse 45",
"zipcode": "10557",
"city": "Berlin",
"countryCode": "DE"
}
},
"packages": [
{
"packageId": "PKG001",
"shipperReference": "PKG-REF-001",
"carrierReference": "CARRIER-PKG-001",
"packageType": "BOX",
"dimensions": {
"length": { "value": 40, "unit": "cm" },
"width": { "value": 30, "unit": "cm" },
"height": { "value": 20, "unit": "cm" },
"grossWeight": { "value": 5.2, "unit": "kg" },
"netWeight": { "value": 4.8, "unit": "kg" }
},
"lineItems": [
{
"lineItemPos": "1",
"itemNumber": "SKU-12345",
"itemDescription": "Premium Wireless Headphones",
"price": { "value": 199.99, "currency": "EUR" },
"quantity": { "quantity": "2", "quantityUnit": "PCS" },
"manufacturingCountry": "CN",
"dimensions": {
"grossWeight": { "value": 0.35, "unit": "kg" }
},
"customsInformation": {
"hsCodes": [ "8518.30.95" ]
}
},
{
"lineItemPos": "2",
"itemNumber": "SKU-67890",
"itemDescription": "Bluetooth Speakers",
"price": { "value": 149.99, "currency": "EUR" },
"quantity": { "quantity": "3", "quantityUnit": "PCS" },
"manufacturingCountry": "CN",
"dimensions": {
"grossWeight": { "value": 0.5, "unit": "kg" }
},
"customsInformation": {
"hsCodes": [ "8518.22.00" ]
}
}
],
"dangerousGoods": [
{
"dangerousGoodsFlag": true,
"dangerousGoodsDetails": {
"dangerousGoodsReference": "DG-REF-001",
"unNumber": "UN3481",
"name": "LITHIUM ION BATTERIES CONTAINED IN EQUIPMENT",
"unClass": "9",
"unPackingGroup": "II"
}
}
]
},
{
"packageId": "PKG002",
"packageType": "BOX",
"dimensions": {
"length": { "value": 25, "unit": "cm" },
"width": { "value": 20, "unit": "cm" },
"height": { "value": 15, "unit": "cm" },
"grossWeight": { "value": 2.3, "unit": "kg" }
},
"lineItems": [
{
"lineItemPos": "1",
"itemNumber": "SKU-54321",
"itemDescription": "USB-C Charging Cables",
"price": { "value": 19.99, "currency": "EUR" },
"quantity": { "quantity": "10", "quantityUnit": "PCS" },
"manufacturingCountry": "VN"
}
]
}
],
"customsInformation": {
"goodsDescription": "Electronic Accessories and Equipment",
"goodsValue": { "value": 849.95, "unit": "EUR" },
"hsCodes": [ "8518.30.95", "8518.22.00", "8544.42.90" ],
"exportDeclarationNumber": "EXP20231015001",
"invoiceNumber": "INV-20231015-001",
"invoiceDate": "2023-10-14"
},
"labelSpecifications": {
"fileFormat": "PDF",
"template": "STANDARD_LABEL"
},
"metaInformation": {
"entry": [
{
"key": "PRINTER_ID",
"value": "12.345.678.910"
}
]
}
}
}
}
Tracking input
To retrieve tracking information, the connector reads CSV configuration files containing carrier-assigned tracking numbers. These files are located under ./conf/Connectors/CEP/Tracking/. Process the tracking responses using the template profile TEMPLATE_LobsterCEP_ShipmentTracking.
Field | Type | Required | Description | Example |
|---|---|---|---|---|
trackingNumber | string | Yes | The carrier-assigned tracking number | 1091847043 |
Each line in the tracking CSV follows this structure:
carrierTrackingNumber;customerShipmentId;latestEventTimestamp;shipmentCreationTimestampThe latestEventTimestamp is filled automatically by the connector and should be left blank in the initial setup.
CSV File per Carrier
Carrier | File Name | Path |
|---|---|---|
DHL Express | List_ShipmentTrackingNumbers_DHL.csv | ./conf/Connectors/CEP/Tracking/ |
FedEx | FEDEX.csv | ./conf/Connectors/CEP/Tracking/ |
UPS | UPS.csv | ./conf/Connectors/CEP/Tracking/ |
PostNL | PostNL.csv | ./conf/Connectors/CEP/Tracking/ |
Example CSV Entry
To track shipment test123 with DHL tracking number 1091847043, created at 2025-09-08 10:00:00, append the following line to List_ShipmentTrackingNumbers_DHL.csv:
1091847043;test123;;1757318400000Note
When you use the shipment booking process, tracking configuration files are automatically created and updated. You only need to manually edit these files for shipments booked outside the connector.
Output data structure
The following structures are what the CEP Connector profile returns to your receiving profile.
Result | Description | Structure |
|---|---|---|
Confirmed | Shipment booked successfully: label and carrier reference returned. | LobsterCEPResponse |
Error | Booking failed: carrier feedback included in response. | Lobster CEPErrorResponse |
Output data structure example—confirmed booking
Returned when a shipment is successfully booked with the carrier. Process using TEMPLATE_LobsterCEP_ShipmentTransportorderAcknowledgement.
Example
{
"LobsterCEP": {
"header": {
"carrierId": "DHL_EXPRESS",
"processingStatus": {
"code": "CONFIRMED",
"realizationDateTime": "2025-08-13T09:33:59+02:00"
}
},
"shipment": {
"shipmentId": "ABC123456789",
"carrierReference": "987654321",
"estimatedDeliveryDate": "2025-08-18T23:59:00Z",
"documents": [
{
"type": "LABEL",
"name": "LABEL_987654321.pdf",
"format": "PDF",
"content": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nO=="
},
{
"type": "INVOICE",
"name": "INVOICE_987654321.pdf",
"format": "PDF",
"content": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nO=="
}
],
"trackingUrl": "https://express.api.dhl.com/mydhlapi/test/shipments/987654321/tracking"
},
"metaInformation": {
"entry": [
{
"key": "PRINTER_ID",
"value": "12.345.678.910"
}
]
}
}
}
Shipment booking—error
Returned when the carrier rejects the shipment booking. Contains the specific error feedback from the carrier.
Example
{
"LobsterCEP": {
"header": {
"carrierId": "DHL_EXPRESS",
"processingStatus": {
"code": "ERROR",
"reason": "1001: The requested product(s) (P) not available based on your search criteria.(68b1955397916e10b04b3650fd5c0071)",
"realizationDateTime": "2025-08-13T09:33:59+02:00"
}
},
"shipment": {
"shipmentId": "ABC123456789"
},
"metaInformation": {
"entry": [
{
"key": "PRINTER_ID",
"value": "12.345.678.910"
}
]
}
}
}
Shipment tracking
Returned by the tracking connector profile with status updates and optional Proof-of-Delivery documents. Process using TEMPLATE_LobsterCEP_ShipmentTracking.
Example
{
"LobsterCEP": {
"header": {
"carrierId": "DHL_EXPRESS"
},
"shipment": [
{
"shipmentId": "ABC123456789",
"carrierReference": "987654321",
"estimatedDeliveryDate": "2025-08-18T23:59:00Z",
"trackingEvents": [
{
"owner": "DHL_EXPRESS",
"creationDateTime": "2025-09-01T10:30:25+02:00",
"eventDateTime": "2025-09-01T01:43:03Z",
"eventLocation": "CPH (Copenhagen-DK)",
"statusDetails": [
{
"code": "OK",
"statusDescription": "Delivered"
}
]
},
{
"owner": "DHL_EXPRESS",
"creationDateTime": "2025-09-01T10:30:25+02:00",
"eventDateTime": "2025-09-01T01:43:08Z",
"eventLocation": "CPH (Copenhagen-DK)",
"statusDetails": [
{
"code": "DF",
"statusDescription": "Shipment has departed from a DHL facility COPENHAGEN-DENMARK"
}
]
}
],
"documents": [
{
"type": "POD",
"name": "POD_987654321.pdf",
"format": "PDF",
"content": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nO=="
}
],
"trackingUrl": "https://express.api.dhl.com/mydhlapi/test/shipments/987654321/tracking"
}
]
}
}
Schema reference
The following sections describe every data structure used within the LobsterCEP format in detail.
Header
Carrier selection, action type, and requested documents.
Required fields: carrierId, action
Field | Type | Required | Description | Allowed values | Example |
|---|---|---|---|---|---|
carrierId | string | Yes | The carrier to handle the shipment | DHL_EXPRESS, FEDEX, UPS, POSTNL | DHL_EXPRESS |
action | string | Yes | The action to perform on the shipment | CREATE | CREATE |
requestedDocuments | array of string | No | Documents to be returned by the carrier. Labels are always auto-requested. | LABEL, COMMERCIAL_INVOICE | LABEL |
Shipment
Full shipment details, including parties, packages, and customs.
Required fields: shipmentId, shipperReference, serviceType, shippingDateTime, accountNumber, parties, packages
Field | Type | Required | Description | Example |
|---|---|---|---|---|
shipmentId | string | Yes | Unique identifier for the shipment. It can be identical to shipperReference. | SHP12345678 |
shipperReference | string | Yes | Shipper's reference for the shipment | REF987654 |
carrierReference | string | No | Carrier's reference number. Normally generated on the CEP side. For DHL Express, you can set your waybill number. | TRKNUM123456 |
consigneeReference | string | No | Recipient's reference number | PO-5432100 |
orderNumbers | OrderNumbers | No | Order numbers related to the shipment | |
serviceType | string | Yes | Type of shipping service (carrier-specific, see table below) | P |
additionalServices | array of AdditionalService | No | Additional services requested for the shipment | |
shippingDateTime | string (date-time) | Yes | Date and time for shipping | 2023-08-15T08:30:00.000Z |
incoTerm | string | No | International Commercial Terms | DAP |
incoTermLocation | string | No | Location for the Incoterm | Destination |
movementType | string | No | Type of movement. Used to determine inbound/outbound commodity code for DHL Express. | OUTBOUND |
pickupRequestedFlag | boolean | No | Whether pickup is requested | true |
dropOffFlag | boolean | No | Whether drop-off is requested | false |
accountNumber | AccountNumber | Yes | Account information for shipping | |
paymentInformation | PaymentInformationWrapper | No | Account information for billing | |
parties | Parties | Yes | All parties involved in the shipment | |
packages | array of Package | Yes | Packages in the shipment | |
customsInformation | CustomsInformation | No | Shipment-level customs information | |
labelSpecifications | LabelSpecifications | No | Label file format and template |
Service type values by carrier
Carrier | Valid values |
|---|---|
DHL Express | P, 1, C, D, E, H, I, K, L, M, N, O, Q, T, U, W, X, Y |
FedEx | FEDEX_INTERNATIONAL_PRIORITY_EXPRESS, INTERNATIONAL_FIRST, FEDEX_INTERNATIONAL_PRIORITY, INTERNATIONAL_ECONOMY, FEDEX_GROUND, FIRST_OVERNIGHT, FEDEX_FIRST_FREIGHT, FEDEX_1_DAY_FREIGHT, FEDEX_2_DAY_FREIGHT, FEDEX_3_DAY_FREIGHT, INTERNATIONAL_PRIORITY_FREIGHT, INTERNATIONAL_ECONOMY_FREIGHT, FEDEX_INTERNATIONAL_DEFERRED_FREIGHT, INTERNATIONAL_PRIORITY_DISTRIBUTION, INTERNATIONAL_DISTRIBUTION_FREIGHT, INTL_GROUND_DISTRIBUTION, GROUND_HOME_DELIVERY, SMART_POST, PRIORITY_OVERNIGHT, STANDARD_OVERNIGHT, FEDEX_2_DAY, FEDEX_2_DAY_AM, FEDEX_EXPRESS_SAVER, SAME_DAY, SAME_DAY_CITY |
UPS | 01, 02, 03, 07, 08, 11, 12, 13, 14, 17, 54, 59, 65, M2, M3, M4, M5, M6, M7, 70, 71, 72, 74, 75, 82, 83, 84, 85, 86, 93, 96, C6, C7, C8, T0, T1 |
PostNL | ProductCode (default 3085) | Characteristic | Option |
Incoterm values
EXW, FCA, CPT, CIP, DAP, DPU, DDP
Movement type values
INBOUND, OUTBOUND
OrderNumbers
Order numbers related to a shipment, package, or line item.
Field | Type | Description | Example |
|---|---|---|---|
salesOrderNumbers | array of string | Sales order numbers | SO123456 |
purchaseOrderNumbers | array of string | Purchase order numbers | PO987654 |
AdditionalService
Additional service requested for the shipment. Only used for DHL Express. For detailed explanations, visit the DHL Express API reference and download the ExpressReferenceData file.
Required fields: serviceCode
Field | Type | Required | Description | Example |
|---|---|---|---|---|
serviceCode | string | Yes | Code for the additional service (DHL Express only). See DHL ExpressReferenceData for the full list of valid codes. | WY |
serviceDescription | string | No | Description of the additional service. Currently not in use. | Paperless Trade |
AccountNumber
Account information for shipping.
Required fields: value
Field | Type | Required | Description | Example |
|---|---|---|---|---|
value | string | Yes | Account number | 123456789 |
PaymentInformation (Wrapper)
Billing information wrapper containing transportation and duties/taxes payment details.
Field | Type | Description |
|---|---|---|
transportation | PaymentInformation | Payment details for transportation charges |
dutiesAndTaxes | PaymentInformation | Payment details for duties and taxes |
PaymentInformation
Billing/payment details for charges.
Field | Type | Description | Allowed values | Example |
|---|---|---|---|---|
paymentType | string | Who is responsible for payment | SHIPPER, RECEIVER, THIRD_PARTY | RECEIVER |
accountNumber | string | Billing account number with the carrier | 123456789 | |
countryCode | string | ISO 3166-1 alpha-2 country code for the billing account | DE |
Parties
All parties involved in the shipment.
Required fields: shipper, recipient
Field | Type | Required | Description |
|---|---|---|---|
shipper | Address | Yes | Shipper address and contact |
recipient | Address | Yes | Recipient address and contact |
pickupAddress | Address | No | Pickup address |
deliveryAddress | Address | No | Delivery address |
ultimateConsignee | Address | No | Ultimate consignee |
importer | Address | No | Importer |
exporter | Address | No | Exporter |
buyer | Address | No | Buyer |
payer | Address | No | Payer |
Address
Address and contact information for any party.
Required fields: name1, street1, zipcode, city, countryCode
Field | Type | Required | Description | Example |
|---|---|---|---|---|
addressIdentifiers | array of AddressIdentifier | No | Additional address identifiers | |
reference | string | No | External customer reference | CUST001 |
name1 | string | Yes | Primary name (usually company name) | Acme Corporation |
name2 | string | No | Secondary name (e.g., department) | Shipping Department |
name3 | string | No | Tertiary name | Building A |
street1 | string | Yes | Street address, line 1 | 123 Main St. |
street2 | string | No | Street address, line 2 | Suite 100 |
zipcode | string | Yes | Postal/ZIP code | 12345 |
city | string | Yes | City name | Berlin |
countryCode | string | Yes | Country code (ISO) | DE |
countryName | string | No | Country name | Germany |
stateCode | string | No | State/province code | BE |
stateName | string | No | State/province name | Berlin |
contacts | array of Contact | No | Contact persons |
AddressIdentifier
Additional address identifier.
Required fields: identifierValue, identifierType
Field | Type | Required | Description | Allowed values | Example |
|---|---|---|---|---|---|
identifierValue | string | Yes | Value of the identifier | DE123456789 | |
identifierType | string | Yes | Type of the identifier | VAT, EOR, UEN, GLN | VAT |
Contact
Contact person information.
Required fields: name, phone
Field | Type | Required | Description | Example |
|---|---|---|---|---|
name | string | Yes | Contact name | John Doe |
string | No | Email address | john.doe@example.com | |
phone | string | Yes | Phone number | +49 30 12345678 |
fax | string | No | Fax number | +49 30 87654321 |
Package
Package dimensions, line items, and dangerous goods.
Required fields: packageId, shipperReference, dimensions
Field | Type | Required | Description | Example |
|---|---|---|---|---|
packageId | string | Yes | Package identifier | PKG001 |
shipperReference | string | Yes | Shipper's reference for this package | SHPREF001 |
carrierReference | string | No | Carrier's reference for this package | CREF001 |
consigneeReference | string | No | Recipient's reference for this package | CONREF001 |
ssccCode | string | No | Serial Shipping Container Code | 00012345600000000018 |
orderNumbers | OrderNumbers | No | Order numbers related to this package | |
packageType | string | No | Type of package (currently not in use) | BOX |
dimensions | Dimensions | Yes | Physical dimensions of the package | |
lineItems | array of LineItem | No | Line items in the package | |
customsInformation | PackageCustomsInformation | No | Package-level customs information | |
dangerousGoods | array of DangerousGoods | No | Dangerous goods information |
Dimensions
Physical dimensions, including weight and volume.
Required fields: grossWeight
Field | Type | Required | Description |
|---|---|---|---|
length | Measurement | No | Length measurement |
width | Measurement | No | Width measurement |
height | Measurement | No | Height measurement |
grossWeight | Weight | Yes | Gross weight |
netWeight | Weight | No | Net weight |
grossVolume | Volume | No | Gross volume |
netVolume | Volume | No | Net volume |
Measurement
Measurement with value and unit.
Required fields: value, unit
Field | Type | Required | Description | Allowed values | Example |
|---|---|---|---|---|---|
value | number | Yes | The measurement value | 10.5 | |
unit | string | Yes | The measurement unit | cm, m, in | cm |
Weight
Weight with value and unit.
Required fields: value, unit
Field | Type | Required | Description | Allowed values | Example |
|---|---|---|---|---|---|
value | number | Yes | The weight value | 10.5 | |
unit | string | Yes | The weight unit | g, kg, lb | kg |
Volume
Volume with value and unit.
Required fields: value, unit
Field | Type | Required | Description | Allowed values | Example |
|---|---|---|---|---|---|
value | number | Yes | The volume value | 10.5 | |
unit | string | Yes | The volume unit | cm3, m3, ft3 | cm3 |
LineItem
Individual line item within a package.
Required fields: itemNumber
Field | Type | Required | Description | Example |
|---|---|---|---|---|
lineItemPos | string | No | Position in line items list | 1 |
itemNumber | string | Yes | Item number/SKU | SKU12345 |
orderNumbers | OrderNumbers | No | Order numbers related to this line item | |
itemDescription | string | No | Description of the item | Blue T-shirt, size L |
price | object | No | Price with value (number) and currency (ISO 4217 three-letter code) | {"value": 29.99, "currency": "EUR"} |
quantity | object | No | Quantity with quantity (string) and quantityUnit (string, carrier-specific codes) | {"quantity": "3", "quantityUnit": "PCS"} |
manufacturingCountry | string | No | Country of manufacture | CN |
exportReasonType | string | No | Reason of export. Only used for DHL Express. | permanent |
dimensions | Dimensions | No | Physical dimensions of the line item | |
customsInformation | LineItemCustomsInformation | No | Line item customs information | |
dangerousGoodsReference | string | No | Reference to dangerous goods information | DG-REF-001 |
Export reason type values (DHL Express only)
permanent, temporary, return, used_exhibition_goods_to_origin, intercompany_use, commercial_purpose_or_sale, personal_belongings_or_personal_use, sample, gift, return_to_origin, warranty_replacement, diplomatic_goods, defence_material
DangerousGoods
Dangerous goods classification and details.
Required fields: dangerousGoodsFlag
Field | Type | Required | Description | Example |
|---|---|---|---|---|
dangerousGoodsFlag | boolean | Yes | Indicates if item contains dangerous goods | true |
dangerousGoodsDetails | object | No | Details of the dangerous goods |
DangerousGoods Details
Field | Type | Description | Example |
|---|---|---|---|
dangerousGoodsReference | string | Reference identifier for dangerous goods | DG-REF-001 |
unNumber | string | UN number | UN1266 |
name | string | Dangerous goods name | PERFUMERY PRODUCTS |
locale | string | Locale information | en-US |
unClass | string | UN class | 3 |
classificationCode | string | Classification code | F1 |
unPackingGroup | string | UN packing group | II |
CustomsInformation (Shipment level)
Shipment-level customs information.
Field | Type | Description | Example |
|---|---|---|---|
goodsDescription | string | Description of goods for customs | Clothing items for retail |
goodsValue | object | Value of goods with value (number) and unit (ISO 4217 currency code) | {"value": 849.95, "unit": "EUR"} |
hsCodes | array of string | Harmonized System codes | 6109.10.00 |
exportDeclarationNumber | string | Export declaration number | EXP20231015001 |
invoiceNumber | string | Commercial invoice number | INV-20231015-001 |
invoiceDate | string | Date of invoice | 2023-10-14 |
PackageCustomsInformation
Package-level customs information.
Field | Type | Description | Example |
|---|---|---|---|
goodsDescription | string | Description of goods for customs | Clothing items for retail |
goodsValue | object | Value of goods with value (number) and unit (ISO 4217 currency code) | {"value": 149.99, "unit": "EUR"} |
LineItemCustomsInformation
Line item-level customs information.
Field | Type | Description | Example |
|---|---|---|---|
goodsDescription | string | Description of goods for customs | Clothing items for retail |
goodsValue | object | Value of goods with value (number) and unit (ISO 4217 currency code) | {"value": 199.99, "unit": "EUR"} |
hsCodes | array of string | Harmonized System codes | 8518.30.95 |
LabelSpecifications
Label file format and template.
Field | Type | Description | Allowed values | Example |
|---|---|---|---|---|
fileFormat | string | Format of the label file. DHL Express: PDF, ZPL, LP2, EPL. UPS: EPL, SPL, ZPL, GIF. FedEx: Not used. | PDF, ZPL, LP2, EPL, SPL, GIF | |
template | string | Template identifier for the label. Default is ECOM26_84_001. Only used for DHL Express. | ECOM26_84_A4_001, ECOM26_84_001, ECOM_TC_A4, ECOM26_A6_002, ECOM26_84CI_001, ECOM26_84CI_002, ECOM26_84CI_003, ECOM_A4_RU_002, ECOM26_84_LBBX_001, ECOM26_64_LBBX_001 | ECOM26_84_001 |
ResponseHeader
Header information returned by the connector in booking acknowledgements and tracking responses.
Required fields: carrierId
Field | Type | Required | Description | Allowed values | Example |
|---|---|---|---|---|---|
carrierId | string | Yes | Carrier identifier | DHL_EXPRESS, FEDEX, UPS | DHL_EXPRESS |
processingStatus | ProcessingStatus | No | Processing result code and timestamp |
ProcessingStatus
Processing result code and timestamp.
Required fields: code, realizationDateTime
Field | Type | Required | Description | Allowed values | Example |
|---|---|---|---|---|---|
code | string | Yes | Processing status code | CONFIRMED, ERROR | CONFIRMED |
reason | string | No | Reason describing the code in case of ERROR | 1001: The requested product(s) (P) not available | |
realizationDateTime | string (date-time) | Yes | Timestamp of the processing result | 2025-08-13T09:33:59+02:00 |
ShipmentAcknowledgement
Successful shipment booking acknowledgement data.
Required fields: shipmentId, carrierReference
Field | Type | Required | Description | Example |
|---|---|---|---|---|
shipmentId | string | Yes | Your shipment identifier echoed back | ABC123456789 |
carrierReference | string | Yes | Carrier-assigned tracking/reference number | 987654321 |
estimatedDeliveryDate | string (date-time) | No | Estimated delivery date and time | 2025-08-18T23:59:00Z |
documents | array of Document | No | Labels, invoices, or other documents | |
trackingUrl | string (uri) | No | URL for tracking the shipment | https://express.api.dhl.com/mydhlapi/test/shipments/987654321/tracking |
ShipmentErrorAcknowledgement
Error response from shipment booking. The error details are in the header's processingStatus.
Required fields: shipmentId
Field | Type | Required | Description | Example |
|---|---|---|---|---|
shipmentId | string | Yes | Your shipment identifier echoed back | ABC123456789 |
ShipmentTracking
Shipment tracking data returned by the tracking connector.
Required fields: shipmentId, carrierReference
Field | Type | Required | Description | Example |
|---|---|---|---|---|
shipmentId | string | Yes | Your shipment identifier | ABC123456789 |
carrierReference | string | Yes | Carrier-assigned tracking number | 987654321 |
estimatedDeliveryDate | string (date-time) | No | Estimated delivery date | 2025-08-18T23:59:00Z |
trackingEvents | array of TrackingEvent | No | List of tracking status events | |
documents | array of Document | No | Documents such as Proof-of-Delivery | |
trackingUrl | string (uri) | No | URL for tracking the shipment | https://express.api.dhl.com/mydhlapi/test/shipments/987654321/tracking |
TrackingEvent
Individual tracking status event.
Required fields: eventDateTime, statusDetails
Field | Type | Required | Description | Example |
|---|---|---|---|---|
owner | string | No | Owner of this status | DHL_EXPRESS |
creationDateTime | string (date-time) | No | Creation date and time of the event | 2023-08-15T10:30:00Z |
eventDateTime | string (date-time) | Yes | Date and time when the event occurred | 2023-08-15T10:15:00Z |
eventLocation | string | No | Location where the event occurred | Berlin Sorting Center |
statusDetails | object | Yes | Status code, reason and description | |
signedBy | string | No | Name of person who signed for delivery | J. Smith |
Status Details
Required fields: statusCode
Field | Type | Required | Description | Example |
|---|---|---|---|---|
statusCode | string | Yes | Status code | PICKED_UP |
statusReason | string | No | Reason for the status | Package picked up by courier |
statusDescription | string | No | Description of the status | The package has been picked up and is now in transit |
Document
Label, invoice, or Proof-of-Delivery document in base64 encoding.
Required fields: type, name, format, content
Field | Type | Required | Description | Example |
|---|---|---|---|---|
type | string | Yes | Document type | LABEL, INVOICE, POD |
name | string | Yes | Document file name | LABEL_987654321.pdf |
format | string | Yes | Document format | |
content | string | Yes | Base64-encoded document content | JVBERi0xLjQK… |
MetaInformation
Key-value metadata passed through the connector. It can be used to temporarily store values through the connector request to later use them in the response.
Required fields: entry
Field | Type | Required | Description |
|---|---|---|---|
entry | array of MetaEntry | Yes | Array of key-value pairs |
MetaEntry
Required fields: key, value
Field | Type | Required | Description | Example |
|---|---|---|---|---|
key | string | Yes | Meta entry key | PRINTER_ID |
value | string | Yes | Meta entry value | 12.345.678.910 |