Skip to main content
Skip table of contents

Creation of Expedition

Create Expedition

Create a new expedition entity to the database.

Request structure

Endpoint:

POST /api/expedition

URL (prod):

https://app.mailship.eu/api/expedition

Headers:

CODE
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Request body:

For detailed request body specifications, please refer to our API Doc.

Request Example (cURL):

CODE
curl --location "https://app.mailship.eu/api/expedition" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer {{token}}" \
--data-raw "{
    \"eshop\": \"eee7067d-ad43-4848-a1f4-e5574ebec896\",
    \"warehouse\": \"cdf15196-51e9-456c-b115-6459b3741367\",
    \"wms\": \"6bfd4074-7839-4c42-9eb2-6760bc1bf479\",
    \"partner\": null,
    \"orderNumber\": \"testDevPortal6\",
    \"note\": \"Handle with care.\",
    \"billingFirstName\": \"John\",
    \"billingLastName\": \"Doe\",
    \"billingDegree\": \"Doc.\",
    \"billingCompany\": \"Mail Step a. s.\",
    \"billingStreet\": \"Street\",
    \"billingHouseNr\": \"315\/2a\",
    \"billingZip\": \"15012\",
    \"billingCity\": \"City\",
    \"billingCountry\": \"CZ\",
    \"billingState\": \"TX\",
    \"billingEmail\": \"john.doe@example.com\",
    \"billingPhone\": \"+420 123456789\",
    \"billingRegistrationNumber\": \"12345678\",
    \"billingVatNumber\": \"CZ12345678\",
    \"differentDeliveryAddress\": true,
    \"deliveryFirstName\": \"John\",
    \"deliveryLastName\": \"Doe\",
    \"deliveryDegree\": \"Doc.\",
    \"deliveryCompany\": \"Mail Step a. s.\",
    \"deliveryStreet\": \"Street\",
    \"deliveryHouseNr\": \"315\/2a\",
    \"deliveryZip\": \"15012\",
    \"deliveryCity\": \"City\",
    \"deliveryCountry\": \"CZ\",
    \"deliveryState\": \"TX\",
    \"deliveryEmail\": \"john.doe@example.com\",
    \"deliveryPhone\": \"+420 123456789\",
    \"requiredExpeditionDate\": \"2025-03-31\",
    \"carrier\": \"801aa52b-acd3-44a5-8316-802eba8c25e9\",
    \"carrierService\": \"8ffccb91-991e-4aac-9615-80e668a50492\",
    \"carrierPickupPlace\": \"e0490e3d-8dbb-4d47-8247-5638a645b34a\",
    \"carrierPickupPlaceCode\": \"21934\",
    \"externalCarrierPickupPlace\": null,
    \"externalCarrierPickupPlaceCode\": null,
    \"carrierNote\": null,
    \"value\": 100,
    \"currency\": \"CZK\",
    \"fragile\": false,
    \"cod\": false,
    \"codValue\": null,
    \"codCurrency\": null,
    \"codVariableSymbol\": null,
    \"customerGroup\": null,
    \"eshopOrderDate\": \"2025-02-21T01:00:00+01:00\",
    \"items\": [
        {
            \"product\": \"dfcee9b9-97aa-497f-aaca-887f28aa68b9\",
            \"quantity\": 1
        }
    ],
    \"waitBeforeProcessing\": false,
    \"editBeforeProcessing\": true,
    \"priority\": null,
    \"ref1\": null,
    \"ref2\": null,
    \"ref3\": null,
    \"b2b\": null
}"

Request body specifications

Here is an additional, more detailed explanation of certain fields:

Field

Description

"eshop"

ID of your e-shop. Retrieve available e-shop IDs via POST /api/eshop/list.

"warehouse"

ID of your warehouse. Retrieve available warehouse IDs via POST /api/warehouse/list.

Warehouse is your physical warehouse.

"wms"

ID of your wms. A wms entity represents a virtual warehouse linked to a physical warehouse. It tracks inventory, stock movements, and shipments within the system, ensuring accurate stock records.

Retrieve your wms ID via POST /api/warehouse/list.

"partner"

You can create a partner in Mailship via POST /api/partner. Useful for recurring B2B customers. Retrieve all your partner IDs via POST /api/partner/list endpoint.

See more for partners in Knowledge Base or API Doc.

"differentDeliveryAddress"

Boolean. If true, delivery address fields must be filled.

"carrier"

ID of the carrier. Retrieve available carrier IDs via POST /api/carrier/list. For more information please see Carrier section.

"carrierService"

ID of the carrier service. Retrieve available carrier services IDs via POST /api/carrier-service/list.

"carrierPickupPlace"

ID of the carrier pickup places. Retrieve available carrier pickup places via POST /api/carrier-pickup-place/list.

"carrierPickupPlaceCode"

Code of the pickup place on the carrier's side. Example values:

  • "27186"- Packeta

  • "KM12514900" - PPL

"externalCarrierPickupPlace"

ID of the external carrier pickup places. Retrieve available carrier external pickup places via POST /api/external-carrier-pickup-place/list.

"externalCarrierPickupPlaceCode"

Code of the external pickup place on the carrier's side. Example value:

  • "26639" - Packeta

"cod"

Boolean. Indicates if cash-on-delivery is required.

"codValue", "codCurrency", "codVariableSymbol"

Fields must be null when cod is false.

"items"

Array of products included in the expedition.

"waitBeforeProcessing"

Boolean. Puts the status “to_be_confirmed“ on the order. Useful for pending payments. The expedition stays in this status until it is manually sent via PUT /api/expedition/{id}/send, triggering processing in WMS.

"editBeforeProcessing"

Boolean. Puts the status “on_hold” on the order, allowing edits before sending to WMS. The expedition stays in this status until it is manually sent via PUT /api/expedition/{id}/send, triggering processing in WMS.

"ignoreAddressValidation"

Boolean. Default: false.

"carrierOptions"

Includes the field "recipientIdentificationNumber", required for DHL Connect when shipping to a pickup point.

"services"

Specialized expedition service. For more information, contact our customer support team.

For additional field informations, refer to the Knowledge Base or API doc.

These fields are not supported and should be excluded when creating an expedition.

CODE
"user"
"status"
"expeditedCompletely"
"invoice"
"createdAt"
"parcels"
"countOfItems"
"countOfSku"
"sumOfQuantity"
"errors"
"packedAt"
"sentAt"
"deliveredAt"
"foreignPrice"
"conversionDate"
"modifiedAt"
"removedVirtualProducts"
"addressValidationExecuted"
"changedAt"
"dcCodeOfOrigin"
"hasDuplicatePositions"
"withComplaint"
"trackingNumber"
"trackingUrl"
"genericTrackingUrl"
"externalTrackingNumber"
"packagesCount"
"priority"

 

Response

If successful, the API returns the newly created expedition entity in JSON format.

See more details in the API Doc.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.