Table of Contents

Create Shipment API

POST /api/v3/shipments

Overview

The Create Shipment API creates a new shipment in Fredi and generates carrier label(s) based on the configured carrier integration.

Note

Fredi acts as a middleware layer that manages carrier communication, label generation, customs processing, and tracking synchronization internally!

Endpoint

POST /api/v3/shipments

Authentication

All requests must include a valid Bearer token.

Header Required Description
Authorization Yes Bearer {access_token}
Content-Type Yes application/json

See: Authentication section for token generation.

Request Body

The Create Shipment API expects a JSON payload containing a shipment array. Each element in the array represents a shipment to be created.

{
  "shipment": [
    {
      "settings": {},
      "carrierDetails": {},
      "shipmentInfo": {}
    }
  ]
}
Note

The request supports batch shipment creation using the shipment[] array!

Top-Level Object

Field Type Required Description
shipment array Yes List of shipment objects. The API supports sending multiple shipments in one request. Each object represents a single shipment.

Shipment Objects

Field Type Required Description
settings object Yes Controls label generation and document settings
carrierDetails object Yes Carrier configuration
shipmentInfo object Yes Shipment data including addresses and packages

Structure

Note

The schema tree below is automatically generated from the OpenAPI specification!

📋 Click a field to see its JSON path

Loading schema…

Note

The example below is automatically generated from the OpenAPI specification!

Sample Request

Show Sample Request 
{
  "shipment": [
    {
      "settings": {
        "loadingLocation": "WH-01",
        "packingStation": "PS-05",
        "documentLanguage": "EN",
        "printDocuments": true,
        "printSettings": {
          "splitByParcel": false,
          "labelType": "PDF",
          "labelSize": "A6",
          "printLabel": true
        }
      },
      "carrierDetails": {
        "carrierCode": "DHL24",
        "carrierContractNumber": "DHL-INT-45872",
        "productCode": "PI",
        "orderType": "STANDARD",
        "shippingType": "AIR",
        "carrierService": [
          {
            "serviceCode": "SIGNATURE_REQUIRED",
            "serviceInformation": [
              {
                "key": "signatureType",
                "value": "ADULT"
              }
            ]
          }
        ]
      },
      "shipmentInfo": {
        "shipmentReference": "SHIP20260317-INT",
        "deliveryNoteNumber": "DN-88921",
        "currency": "EUR",
        "grossAmount": 1250,
        "grossAmountCurrency": "EUR",
        "invoiceNumber": "INV-44567",
        "orderNumber": "ORD-99001",
        "customerOrderNumber": "CUST-88991",
        "description": "Electronic components",
        "incotermCode": "DAP",
        "frankingCode": "PREPAID",
        "addressData": [
          {
            "sender": {
              "addressType": "BUSINESS",
              "customerNumber": "CUST-1001",
              "name": "TechSource GmbH",
              "name2": "Warehouse Division",
              "name3": "",
              "street": "Industriestrasse",
              "street2": "",
              "houseNo": "21A",
              "postalCode": "80331",
              "city": "Munich",
              "countryIsoCode": "DE",
              "provinceCode": "BY",
              "vatNumber": "DE123456789",
              "contactPerson": {
                "name": "Max Müller",
                "phone": "+4989123456",
                "mobile": "+491701234567",
                "fax": "",
                "email": "jon.snow@techsource.de"
              }
            },
            "recipient": {
              "addressType": "BUSINESS",
              "customerNumber": "CUST-2001",
              "name": "Global Retail Ltd",
              "name2": "",
              "name3": "",
              "street": "Market Street",
              "street2": "",
              "houseNo": "455",
              "postalCode": "94105",
              "city": "San Francisco",
              "countryIsoCode": "US",
              "provinceCode": "CA",
              "vatNumber": "",
              "contactPerson": {
                "name": "Daenerys T",
                "phone": "+14155550123",
                "mobile": "+14155559876",
                "fax": "",
                "email": "daenerys.t@globalretail.com"
              }
            }
          }
        ],

        "paymentInfo": {
          "shippingChargesPayment": {
            "payer": "SENDER",
            "accountNumber": "ACC-778899"
          }
        },

        "additionalInformation": {
          "fedexIntegrator": {
            "packagingType": "YOUR_PACKAGING"
          }
        },

        "pickup": {
          "pickupType": "SCHEDULED",
          "date": "2026-03-10"
        },

        "international": {
          "declaredValueAmount": 1250,
          "declaredValueCurrency": "EUR",
          "containsDocuments": false
        },

        "shipmentItems": [
          {
            "packageCode": "BOX",
            "packageReference1": "PKG-10001",
            "dimensions": {
              "length": 40,
              "width": 30,
              "height": 20,
              "unitOfMeasurement": "CM"
            },
            "netWeight": 8,
            "grossWeight": 10,
            "grossWeightUom": "KG",
            "quantity": 1,
            "content": "Electronic components",

            "international": {
              "exportType": "PERMANENT",
              "additionalChargesAmount": 0,
              "additionalChargesCurrency": "EUR"
            },

            "articles": [
              {
                "articleNumber": "ART-1001",
                "description": "Microcontroller Units",
                "numberOfPieces": 50,
                "quantity": 50,
                "quantityUom": "PCS",
                "singlePrice": 20,
                "price": 1000,
                "priceCurrency": "EUR",
                "netWeight": 5,
                "grossWeight": 6,
                "grossWeightUom": "KG",
                "tariffNumber": "85423190",
                "countryOfOrigin": "DE",
                "stateOfOrigin": "BY",
                "length": 10,
                "width": 5,
                "height": 2
              }
            ],
            "packages": []
          }
        ]
      }
    }
  ]
}

Responses

Code Description
200 Success – Shipment created successfully.
201 Success – Shipment saved successfully.
400 Bad Request – invalid shipment data.
401 Unauthorized – user is not authenticated or lacks required role
422 Validation Error
500 Internal Server Error

Response Format

200 Success – Shipment created successfully 
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.3.1",
  "title": "Success – Shipment created successfully",
  "status": 200,
  "data": {
    "shipmentReference": "SHIP-100045",
    "carrierCode": "DHL",
    "trackingNumber": "JD014600006542345678",
    "labelGenerated": true,
    "documents": [
      {
        "documentType": "LABEL",
        "format": "PDF",
        "content": "base64EncodedLabelContent"
      }
    ]
  }
}

Field Description

Field Type Description
type string Reference to the HTTP specification for the response type.
title string Short message describing the result of the request.
status integer HTTP status code returned by the API.
data object Contains shipment details generated after successful processing.
data.shipmentReference string Unique identifier for the created shipment.
data.carrierCode string Carrier used for the shipment.
data.trackingNumber string Tracking number assigned by the carrier.
data.labelGenerated boolean Indicates whether the shipping label was successfully generated.
data.documents array List of documents returned by the API (for example, shipping labels).

400 Bad Request 
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "$": [
      "':' is invalid after a single JSON value. Expected end of data. **Path**: $ | LineNumber: 0 | BytePositionInLine: 10."
    ],
    "objShipment": [
      "The objShipment field is required."
    ]
  },
  "traceId": "00-0a9e238310fc1a3ee316c4f1ef554ed9-e4028dfefbc4b5a7-00"
}

Field Description

Field Type Description
type string URL reference to the HTTP specification describing the error type.
title string Short description of the error.
status integer HTTP status code returned by the API.
errors object Contains detailed validation errors for specific fields.
errors.$ array JSON parsing errors related to the request body format.
errors.objShipment array Indicates that the required objShipment field is missing.
traceId string Unique identifier used for tracing the request in server logs.

Important Notes

  • Carrier-specific fields depend on configured carrier integrations.
  • International fields are mandatory for cross-border shipments.
  • Dangerous goods must comply with carrier restrictions.
  • Label generation depends on carrier configuration.
Back to top ↑