⚡ Shipment Workflows

Shipment API Workflow for Shipment Creation

Step 1: Authentication

In the first step, you authenticate using the provided API key to request an access token. A detailed explanation is available in the Authentication section.

https://api-uat.sevensenders.com/v2/token

https://api.sevensenders.com/v2/token

Authentication

Authentication is handled via an API key that is assigned to you for the duration of the project. Upon sending the request, the system returns an access token, which remains valid for 60 minutes.

{
  "access_key": "your_apikey"
}

{
  "token": "your_token"
}

Use the returned token in the Authorization header of subsequent requests likePOST Shipmentor GET Shipment

Authorization: Bearer your_token

Step 2. Create a Shipment

A full list of all available parameters — including allowed values and whether they are mandatory or optional — can be found in the parameter reference.

https://api-uat.sevensenders.com/v2/shipment

https://api.sevensenders.com/v2/shipment

Generate Shipment via POST Shipment Request

In the following request, a shipment is created. It includes the fundamental parameters required to generate a shipment.

{
  "carrier": {
    "country": "DE",
    "name": "prime-network"
  },
  "carrier_service": "standard",
  "cod_reference": "COD-2024-001",
  "comment": "Please deliver after 3 PM",
  "goods_value": 10.5,
  "goods_value_currency": "EUR",
  "local_delivery": false,
  "order": {
    "boarding_complete": true,
    "language": "en",
    "order_date": "2024-01-15T10:30:00Z",
    "order_id": "ORD-2024-001234",
    "order_tags": {
      "tag1": "value1",
      "tag2": "value2"
    },
    "order_url": "https://shop.example.com/orders/ORD-2024-001234",
    "promised_delivery_date": "2024-01-20T23:59:59Z"
  },
  "order_id": "ORD-2024-001234",
  "pickup_point_selected": false,
  "planned_pickup_datetime": "2024-01-16T09:00:00Z",
  "recipient_address": "Hauptstraße 123",
  "recipient_address_details": "Apartment 4B, 2nd floor",
  "recipient_city": "Vienna",
  "recipient_company_name": "Acme Corporation",
  "recipient_country": "AT",
  "recipient_email": "[email protected]",
  "recipient_first_name": "John",
  "recipient_last_name": "Doe",
  "recipient_phone": "+43 1 234 5678",
  "recipient_zip": "1010",
  "reference_number": "SHIP-2024-001234",
  "reference_number_2": "reference number 2",
  "return_parcel": false,
  "shipment_tag": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "trackable": true,
  "tracking_code": "1234567890123",
  "warehouse": "Main Warehouse Vienna",
  "warehouse_address": "Warehouse Street 45, 1100 Vienna, Austria",
  "weight": 2.5
}

{
  "carrier": {
    "country": "DE",
    "name": "prime-network"
  },
  "carrier_service": "standard",
  "carrier_tracking_url": "https://www.carrier.com/tracking?id=1234567890123",
  "cod_reference": "COD-2024-001",
  "comment": "Please deliver after 3 PM",
  "goods_value": 10.5,
  "goods_value_currency": "EUR",
  "id": "12345",
  "local_delivery": false,
  "order_id": "ORD-2024-001234",
  "pickup_point_selected": false,
  "planned_pickup_datetime": "2024-01-16T09:00:00Z",
  "recipient_address": "Hauptstraße 123",
  "recipient_address_details": "Apartment 4B, 2nd floor",
  "recipient_city": "Vienna",
  "recipient_company_name": "Acme Corporation",
  "recipient_country": "AT",
  "recipient_email": "[email protected]",
  "recipient_first_name": "John",
  "recipient_last_name": "Doe",
  "recipient_name": "John Doe",
  "recipient_phone": "+43 1 234 5678",
  "recipient_zip": "1010",
  "reference_number": "SHIP-2024-001234",
  "reference_number_2": "reference number 2",
  "return_parcel": false,
  "shipment_tag": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "trackable": true,
  "tracking_code": "1234567890123",
  "warehouse": "Main Warehouse Vienna",
  "warehouse_address": "Warehouse Street 45, 1100 Vienna, Austria",
  "weight": 2.5
}

When a shipment is successfully created:

Status is automatically set to new
Tracking can begin once carrier scans occur

Step 3. Shipment Lifecycle Overview

flowchart LR

    A["Shipment Created<br/>POST /shipment"]
    A --> B["Status: new"]

    B --> C["Status: pickup"]
    B --> D["Status: info"]

    C --> D
    D --> E["Status: hub scan at LMC"]

    E --> F["Status: out for delivery"]

    F --> G{"Delivery Successful?"}

    G -->|"Yes"| H["Status: delivered"]
    G -->|"No"| I["Status: delivery attempt failed"]

    I --> F

    F --> J{"Delivered to Pickup Point?"}
    J -->|"Yes"| K["Status: delivered to pickup point"]

    E --> L["Status: lost"]

Shipment Status Explanation

Status	Description
new	Shipment has been created in Seven Senders Portal.
pickup	The planned pickup date has been reached. The shipment is scheduled for collection from your warehouse.
info	Shipment information has been electronically announced to the carrier.
hub scan at LMC	First physical scan at the carrier’s hub. The shipment has entered the carrier network.
out for delivery	The shipment is loaded onto the last-mile delivery vehicle. If delivery fails, the shipment remains in this phase until the next attempt.
delivery attempt failed	A delivery attempt was made but unsuccessful. Another attempt may follow.
delivered to pickup point	The shipment has been delivered to a pickup location. This may occur if the customer selected a pickup point or if home delivery failed and the parcel was redirected.
delivered	The shipment has been successfully delivered to the recipient. This is a final status.
lost	The carrier has reported the shipment as lost. This is a final status.

Final Statuses

The following shipment statuses are final:

delivered
lost

Once a shipment reaches one of these states, no further transitions occur.