⚙️ API Parameter Reference

This section provides a complete list of all parameters included in the Post Label Request and Post Label Response. For each parameter, you will find a usage description, accepted values, and whether the parameter is required. If you are looking for case-specific or carrier-specific request examples, you can find them here.

POST Labels Request

Below you will find the full set of parameters in a structured JSON format. The comments serve solely to categorize the individual information blocks.

{
  // Sender Address Data
  "sender_first_name": "Max",
  "sender_last_name": "Mustermann",
  "sender_company_name": "Muster GmbH",
  "sender_street": "Senderstraße",
  "sender_house_no": "10",
  "sender_zip": "1010",
  "sender_city": "Wien",
  "sender_country": "AT",
  "sender_phone": "+43123456789",
  "sender_email": "[email protected]",
  "warehouse": "Main Warehouse Vienna",
  "warehouse_address": "Lagerstraße 5, 1200 Wien, AT",

  // Recipient Address Data
  "recipient_first_name": "Anna",
  "recipient_last_name": "Müller",
  "recipient_company_name": "Müller Handels GmbH",
  "recipient_street": "Mariahilfer Straße",
  "recipient_house_no": "74/2",
  "recipient_address_details": "Top 12, Klingel: Müller",
  "recipient_zip": "1060",
  "recipient_city": "Wien",
  "recipient_country": "AT",
  "recipient_phone": "+436601234567",
  "recipient_email": "[email protected]",

  // PUDO (Pickup & Dropoff Point) Address Data
  "pudo_id": "75689",
  "collection_point_name1": "Paketshop Mariahilfer Straße",
  "collection_point_name2": "im Tabak-Trafik",
  "collection_point_name3": "gegenüber U3",
  "collection_point_membership_id": "PUDO123456",
  "collection_point_street": "Mariahilfer Straße",
  "collection_point_house_no": "76",
  "collection_point_zip": "1060",
  "collection_point_city": "Wien",
  "collection_point_country": "AT",

  // Shipment & Order Data
  "reference_number": "your_unique_shipment_reference",
  "reference_number_2": "non_unique_second_shipment_reference",
  "shipment_tag": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "planned_pickup_datetime": "2025-11-22T10:00:00.000Z",
  "order": {
    "order_id": "your_order_id",
    "order_url": "https://www.your_order_url.at",
    "order_date": "2025-11-21T21:59:23.346Z",
    "boarding_complete": true,
    "language": "de",
    "order_tags": {
      "tag1": "value1",
      "tag2": "value2"
    },
    "promised_delivery_date": "2025-11-30T18:00:00.000Z"
  },

  // Base Shipping Label Specification
  "format": "pdf",
  "carrier": {
    "name": "dpd",
    "country": "AT"
  },
  "carrier_service": "standard",
  "carrier_service_id": "b5829462-a792-4441-9f74-f365a07cf41a",
  "return_parcel": "both",
  "weight": 3,
  "dimensions": {
    "height": 30,
    "length": 20,
    "width": 20
  },

  // Goods Value (for Insurance) & Cash on Delivery Data
  "goods_value": 10.5,
  "goods_value_currency": "EUR",
  "cod": true,
  "cod_value": "10.5",
  "cod_currency": "EUR",
  "cod_reference": "COD-REF-12345",


  // Parcel Content & SKUs Data
  "parcel": {
    "description": "Mobile phone case and charger",
    "skus": [
      {
        "article_id": "EP2017002392",
        "country_of_origin": "DE",
        "arrival_country_description": "Liquid silicone case for mobile phone",
        "arrival_country_tariff_number": 6109100000,
        "qty": 3,
        "total_net_weight": 0.2,
        "total_gross_weight": 0.25,
        "sales_value_total": 19.99,
        "currency": "EUR",
        "return_reason": "Mobile phone case was broken",

        // Dangerous Goods Data
        "dangerous_goods": [
          {
            "un_number": "UN3481",
            "hazard_description": "Lithium ion batteries contained in equipment",
            "technical_name": "Lithium ion batteries",
            "hazard_class": "9",
            "harzard_classification_code": "M4",
            "additional_hazard_id": "DG001",
            "packing_group": "II",
            "packing_instruction_code": "965",
            "flash_point": 12,
            "transport_category": "2",
            "tunnel_code": "E",
            "liquid_volume": {
              "unit": "ml",
              "value": 10
            },
            "net_explosive_mass": 0.05,
            "is_limited_quantities": true,
            "container_type": "fiberboard box",
            "hazard_labels_1": "9",
            "hazard_labels_2": "3",
            "hazard_labels_3": "3"
          }
        ]
      }
    ]
  }
}

{
  // unique reference number
  "reference_number": "your_unique_shipment_reference",

  "tracking_code": "061234567890124",
  // In the case of outbound only, the outbound tracking number is returned.
  // For returns only, the return tracking number is provided.
  // For both, only the return tracking number is used as the main reference.

  // Outbound Shipment Data
  "outbound": {
    "label_url": "https://api-uat.sevensenders.com/v2/label-download/98765431",
    "shipment_id": "98765431",
    "tracking_code": "061234567890123",
    "print_format": "A6",
    "mime_type": "application/pdf",
    "pickup_point_selected": true,
    "return_address": {
      "firstName": "Max",
      "lastName": "Mustermann",
      "company": "Muster GmbH",
      "phone": "+43123456789",
      "email": "[email protected]",
      "street": "Senderstraße",
      "streetNo": "10",
      "zipCode": "1010",
      "city": "Wien",
      "country": "AT",
      "addressDetails": null,
      "province": null
    },
    "carrier": {
      "name": "dpd",
      "country": "AT"
    }
  },
  "goods_value": 10.5,
  "goods_value_currency": "EUR",
  "local_delivery": false,
  
  // Return Shipment Data
  "return": {
    "label_url": "https://api-uat.sevensenders.com/v2/label-download/98765432",
    "shipment_id": "98765432",
    "tracking_code": "061234567890124",
    "print_format": "A6",
    "mime_type": "application/pdf",
    "pickup_point_selected": true,
    "return_address": {
      "firstName": "Max",
      "lastName": "Mustermann",
      "company": "Muster GmbH",
      "phone": "+43123456789",
      "email": "[email protected]",
      "street": "Senderstraße",
      "streetNo": "10",
      "zipCode": "1010",
      "city": "Wien",
      "country": "AT",
      "addressDetails": null,
      "province": null
    },
    "carrier": {
      "name": "dpd",
      "country": "AT"
    }
  }
}

Table of Contents - Information Blocks

• Sender Address Data
• Recipient Address Data
• PUDO (Pickup & Dropoff Point) Address Data
• Shipment & Order Data
• Base Shipping Label Specification
• Goods Value & Cash on Delivery Data
• Parcel Content and SKU Data
• Dangerous Goods Data

Sender Address Data

The sender address parameters are all fully optional. The sender information displayed on the label is retrieved from the backend configuration. However, we still recommend providing the values for warehouse and warehouse_address.

Recipient Address Data

The recipient address data you submit to the Seven Senders API will either appear on the carrier label and/or be transmitted to the carrier as part of the shipment data. Most of these parameters are mandatory, as they are essential for a successful delivery.

ℹ️

We strongly recommend providing recipient_first_name and recipient_last_name in their dedicated fields. If this separation is not possible in your system, please submit a hardcoded value for “recipient_last_name”, such as ".".

ℹ️

We strongly recommend providing recipient_street and recipient_street_no in their dedicated fields. If your system does not support splitting the street name and street number, please include the full value in recipient_street and do not populate recipient_street_no.

ℹ️

recipient_email and recipient_phone are conditional parameters. Depending on the carrier service used, they may be mandatory — for example, if the carrier provides notification services via email or phone as part of their offering, such as sending delivery announcements to improve SLA performance or enabling customers to schedule delivery appointments.

PUDO (Pickup & Dropoff Point) Address Data

If you want to address the shipment to a PUDO point, you must provide the PUDO-specific data. The minimum information you should transmit is the PUDO ID, which uniquely identifies a specific carrier PUDO location.

One way to retrieve the correct PUDO IDs for various carriers and their corresponding PUDO addresses is to use the Seven Senders PUDO Locator API [see here].

ℹ️

Collection Point Parameters and PUDO Fallback

• The collection_point parameters are helpful in determining a fallback PUDO point, should you choose to enable this functionality.
• PUDO Fallback: In cases where you do not provide a PUDO ID, your PUDO ID is invalid, or the specified PUDO point is closed, the fallback logic selects the nearest available PUDO point based on the provided collection address.
  • If no collection address data is available, the recipient address data will be used instead for the fallback determination.

🚧

PUDO - edge case Carriers

Some carriers, such as DHL DE (Germany), are an exception when it comes to PUDO shipments. In these cases, no unique PUDO IDs are available and some of the collection point data becomes mandatory. In addition, DHL DE (Germany) uses dedicated collection_membership_id's that are assigned to recipients and are relevant for identifying the parcel recipient.

Shipment & Order Data

The Shipment and Order data only require two mandatory fields - reference_number & order.order_id However, we strongly recommend providing as many fields as possible so you can fully leverage the Seven Senders product portfolio, such as tracking, notifications, and analytics. For more details, see the Seven Senders products [here].

🚧

Reference_number uniqueness

The reference_number must be unique per shipping label request. For each reference_number, exactly one carrier label is created. It is not possible to generate multiple labels using the same reference_number.

• If you send the same reference_number multiple times within 48 hours, the API will return the originally created label in the response – regardless of any other changes in the JSON payload.
• If you send the same reference_number after 48 hours, the API will return an error response.

Base Shipping Label Specification

The following parameters define the label-specific base information. This includes, for example, the label format to be generated, the selected carrier product or service, and whether an outbound label, a returns label, or both should be created.

ℹ️

Carrier.name and carrier.country & carrier_service_id List

• You can retrieve the list of supported carrier.name and **carrier.country **values through the API (GET v2/carriers - see here).
• For the corresponding carrier_service_id values associated with each carrier, please reach out to your integration contact. In the future, the available carrier service IDs will also be provided directly via the API.
  • If the carrier_service_id is not transmitted, the system automatically selects the default carrier service configured for your setup.
  • However, when working with different service types—such as PUDO or Home delivery—providing the correct value for each label becomes essential.

🚧

return_parcel for outbound, return or both labels

• The return_parcel parameter defines whether you want an outbound label, a return label, or both.
• If set to both, the response returns two label URLs and two tracking codes. This corresponds to the “return label in the outbound box” solution.

ℹ️

Dimensions Data

• Shipment dimensions may be mandatory or optional depending on the carrier.
  • Some carriers enforce strict validation and require accurate, parcel-specific dimension data.
  • Others are less strict and accept default dimension values. Please coordinate with your integration partner to determine the requirements for your specific carrier setup.

Goods Value & Cash on Delivery Data

The Good Value and COD (Cash on Delivery) parameters are required for specific carrier products.

• Use the cod parameters to define the payment amount for Cash on Delivery carrier services.
• The goods_value parameter, on the other hand, specifies the declared value of the shipment for carrier services that include additional insurance.

Parcel Content and SKU Data

Parcel content and SKU data are rarely required. However, when shipping dangerous goods, certain parcel or SKU fields may become mandatory. Requirements vary by carrier, so please refer to the following documentation Shipping Dangerous Goods.

Dangerous Goods Data

Some carriers require a declaration of dangerous goods when shipping such items. The required fields and the level of detail vary significantly by carrier. If you are shipping dangerous goods, please refer to the following documentation Shipping Dangerous Goods.