Guides
Start typing to search…

Shipping Multiple Packages

⚡

TL;DR — Ship multiple boxes in one order:

  1. Get quote → POST /ship/rate/ with multiple items in packages[] array (Shipping)
  2. Create label → POST /ship/generate/ — returns one tracking number per package (Shipping)
  3. Create manifest → POST /ship/manifest to consolidate labels (Shipping)
  4. Track all → POST /ship/generaltrack/ with all tracking numbers (Shipping)
flowchart LR
  Q["Get Quote<br/>(multi-pkg)"] --> L["Create Label<br/>(1 per pkg)"] --> M["Create<br/>Manifest"] --> T["Track All"]
  style L fill:#1873dc,color:#fff
  style M fill:#d97706,color:#fff

Meet Carlos

Carlos manages fulfillment operations for TechStore, an electronics retailer in Mexico City. TechStore has its own customer-facing UI where customers enter their shipping information—address, destination details, and contact information. When customers place orders through TechStore's platform, all the address and destination information they provide is automatically linked and used in the API calls to Envia. While Carlos's customers interact with TechStore's custom UI, all the backend shipping operations are powered by the Envia API.

Today, he's processing an order for a customer in Guadalajara who purchased a laptop, a wireless mouse, a laptop bag, and warranty documentation. These items need to be shipped in separate boxes due to size and packaging requirements, but they're all part of one customer order. Carlos needs to ensure all packages are tracked together and can be picked up efficiently.

Business type

Electronics retailer with fulfillment operations

Challenge

Single customer order requires multiple packages that need to be tracked and consolidated

Solution

Create multiple packages in one shipment, generate labels, and consolidate into a manifest for pickup

Understanding Multiple Packages

When a single order requires multiple boxes, you can include all packages in one shipment request. The advantages of this are:

Business Benefits

  • Lower costs (in most cases) - Single quote for entire shipment vs. individual package pricing
  • Simplified operations - One master label with child labels, all packages share same origin/destination/service
  • Better tracking - Master tracking number links all pieces together

Developer Benefits

  • Automatic calculations - System auto-sums weights and dimensions across all packages
  • Clean data structure - One shipment record + multiple package records with flexible cost/service attribution
  • Unified quoting - Single API call returns price for complete shipment
  • Flexible tracking - Each package can have own tracking number or share one, depending on carrier

Bottom line: MPS saves money and simplifies handling multiple packages going to the same destination, while the technical implementation handles complexity automatically.

The Journey

Carlos's workflow for shipping multiple packages:

1. Prepare Package Details

Define all packages with dimensions, weight, and contents

2. Get Quote with Multiple Packages

Get shipping quote for all packages together

3. Create Label for Multi-Package Shipment

Generate labels with tracking numbers for all packages

4. Create Manifest

Consolidate all packages into one manifest

5. Schedule Pickup

Schedule pickup for all packages

Step-by-Step Workflow

Step 1: Prepare Package Details

What Carlos needs to do: Carlos needs to define all the packages that make up this order. Each package has its own dimensions, weight, and contents. He'll structure this as an array of packages in the shipment request.

Package Details:

  • Package 1: Laptop (weight: 2.5 kg, dimensions: 40x30x5 cm, value: $15,000 MXN)
  • Package 2: Wireless mouse and laptop bag (weight: 0.8 kg, dimensions: 25x20x10 cm, value: $1,200 MXN)
  • Package 3: Warranty documents (weight: 0.1 kg, dimensions: 22x16x2 cm, value: $0 MXN)

Step 2: Get Quote with Multiple Packages

What Carlos needs to do: Carlos will request a quote that includes all three packages. The quote will show the total cost for shipping all packages together.

API Call: Quote Shipments from the Shipping API

curl --request POST \
  --url "https://api-test.envia.com/ship/rate/" \
  --header "Authorization: Bearer $ENVIA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "origin": {
      "name": "Carlos Mendez",
      "company": "TechStore",
      "phone": "+52 5559876543",
      "email": "[email protected]",
      "street": "Av. Reforma 350",
      "city": "Ciudad de Mexico",
      "state": "CMX",
      "country": "MX",
      "postalCode": "06500"
    },
    "destination": {
      "name": "Roberto Silva",
      "phone": "+52 3331234567",
      "street": "Av. Revolucion 456",
      "city": "Guadalajara",
      "state": "JA",
      "country": "MX",
      "postalCode": "44100"
    },
    "packages": [
      {
        "type": "box",
        "content": "Laptop",
        "amount": 1,
        "declaredValue": 15000,
        "weight": 2.5,
        "weightUnit": "KG",
        "lengthUnit": "CM",
        "dimensions": {
          "length": 40,
          "width": 30,
          "height": 5
        }
      },
      {
        "type": "box",
        "content": "Mouse and laptop bag",
        "amount": 1,
        "declaredValue": 1200,
        "weight": 0.8,
        "weightUnit": "KG",
        "lengthUnit": "CM",
        "dimensions": {
          "length": 25,
          "width": 20,
          "height": 10
        }
      },
      {
        "type": "envelope",
        "content": "Warranty documents",
        "amount": 1,
        "declaredValue": 0,
        "weight": 0.1,
        "weightUnit": "KG",
        "lengthUnit": "CM",
        "dimensions": {
          "length": 22,
          "width": 16,
          "height": 2
        }
      }
    ],
    "shipment": {
      "type": 1,
      "carrier": "dhl"
    }
  }'

Response example

{
  "meta": "rate",
  "data": [
    {
      "carrier": "dhl",
      "service": "ground",
      "serviceDescription": "DHL Economy",
      "deliveryEstimate": "3-5 business days",
      "totalPrice": "285.40",
      "currency": "MXN"
    }
  ]
}
📦

Carlos learns: When including multiple packages in one shipment, the quote shows the total cost for shipping all packages together. Each package maintains its own dimensions and declared value, but they're all part of one shipment.

Step 3: Create Label for Multi-Package Shipment

What Carlos needs to do: Carlos will create the shipping label using the same package structure. The response will include tracking information for all packages.

API Call: Create Shipping Label from the Shipping API

curl --request POST \
  --url "https://api-test.envia.com/ship/generate/" \
  --header "Authorization: Bearer $ENVIA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "origin": {
      "name": "Carlos Mendez",
      "company": "TechStore",
      "phone": "+52 5559876543",
      "email": "[email protected]",
      "street": "Av. Reforma 350",
      "city": "Ciudad de Mexico",
      "state": "CMX",
      "country": "MX",
      "postalCode": "06500"
    },
    "destination": {
      "name": "Roberto Silva",
      "phone": "+52 3331234567",
      "street": "Av. Revolucion 456",
      "city": "Guadalajara",
      "state": "JA",
      "country": "MX",
      "postalCode": "44100"
    },
    "packages": [
      {
        "type": "box",
        "content": "Laptop",
        "amount": 1,
        "declaredValue": 15000,
        "weight": 2.5,
        "weightUnit": "KG",
        "lengthUnit": "CM",
        "dimensions": {
          "length": 40,
          "width": 30,
          "height": 5
        }
      },
      {
        "type": "box",
        "content": "Mouse and laptop bag",
        "amount": 1,
        "declaredValue": 1200,
        "weight": 0.8,
        "weightUnit": "KG",
        "lengthUnit": "CM",
        "dimensions": {
          "length": 25,
          "width": 20,
          "height": 10
        }
      },
      {
        "type": "envelope",
        "content": "Warranty documents",
        "amount": 1,
        "declaredValue": 0,
        "weight": 0.1,
        "weightUnit": "KG",
        "lengthUnit": "CM",
        "dimensions": {
          "length": 22,
          "width": 16,
          "height": 2
        }
      }
    ],
    "shipment": {
      "type": 1,
      "carrier": "dhl",
      "service": "ground"
    }
  }'

Response example

{
  "meta": "generate",
  "data": [
    {
      "carrier": "dhl",
      "service": "ground",
      "shipmentId": 987654,
      "trackingNumbers": [
        "7520610403",
        "7520610404",
        "7520610405"
      ],
      "trackUrl": "https://tracking.envia.com/7520610403",
      "label": "https://files.envia.com/labels/7520610403.pdf",
      "totalPrice": 285.4,
      "currency": "MXN"
    }
  ]
}
📋

Carlos notes: The label response includes tracking numbers for all packages. Carlos saves these tracking numbers—he'll need them to create the manifest and track the shipment.

Step 4: Create Manifest

What Carlos needs to do: Now Carlos will create a manifest that consolidates all three packages. This manifest serves as proof of shipment and helps organize packages for pickup. The manifest lists all tracking numbers together.

API Call: Create Manifest from the Shipping API

curl --request POST \
  --url "https://api-test.envia.com/ship/manifest" \
  --header "Authorization: Bearer $ENVIA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "trackingNumbers": [
      "7520610403",
      "7520610404",
      "7520610405"
    ]
  }'

Response example

{
  "meta": "manifest",
  "data": {
    "manifestId": "MAN-2025-001",
    "manifestUrl": "https://files.envia.com/manifests/MAN-2025-001.pdf",
    "totalPackages": 3,
    "carrier": "dhl"
  }
}
📄

Carlos understands: The manifest consolidates all packages into one document. This is useful for warehouse organization, carrier pickup confirmation, and as proof of shipment. Carlos can print the manifest and use it when the carrier arrives for pickup.

Step 5: Schedule Pickup

What Carlos needs to do: Carlos will schedule a pickup for all packages. He can include all tracking numbers in the pickup request, or reference the manifest.

📋

Pickup Rules: Pickup requirements vary by carrier. Carlos should verify cutoff times, available business days, and minimum package counts with each carrier before scheduling. Use the Queries API to check carrier-specific pickup options.

API Call: Schedule Pickup from the Shipping API

⚠️

Example body vs API reference: The request body below uses a simplified flat structure. The canonical API schema uses origin and shipment.pickup as nested objects. Always verify the exact request shape in the Schedule Pickup reference before integrating.

curl --request POST \
  --url "https://api-test.envia.com/ship/pickup/" \
  --header "Authorization: Bearer $ENVIA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "carrier": "dhl",
    "pickupAddress": {
      "name": "Carlos Mendez",
      "company": "TechStore",
      "phone": "+52 5559876543",
      "email": "[email protected]",
      "street": "Av. Reforma 350",
      "city": "Ciudad de Mexico",
      "state": "CMX",
      "country": "MX",
      "postalCode": "06500"
    },
    "pickupDate": "2025-01-27",
    "pickupTimeStart": "14:00",
    "pickupTimeEnd": "17:00",
    "trackingNumbers": [
      "7520610403",
      "7520610404",
      "7520610405"
    ]
  }'

Response example

{
  "meta": "pickup",
  "data": {
    "carrier": "dhl",
    "confirmation": "PKP-2025-001",
    "status": "scheduled",
    "date": "2025-01-27",
    "timeFrom": 14,
    "timeTo": 17
  }
}

What Carlos Learned

Through handling multi-package orders, Carlos discovered:

  1. Multiple packages in one shipment - All packages can be included in a single quote and label request
  2. Manifests organize shipments - Creating a manifest consolidates all packages into one document for easy tracking
  3. Single pickup for multiple packages - All packages can be picked up together using their tracking numbers
  4. Better customer experience - Customers can track all their packages together, even though they're in separate boxes
  5. Efficient warehouse operations - Manifests help warehouse staff organize and prepare packages for pickup

Carlos's customer in Guadalajara received all three packages (laptop, accessories, and warranty documents) together, and Carlos has streamlined his fulfillment process for future multi-package orders!

What to read next

Related references

Updated 11 days ago