Quickstart

Use Case

Use this quickstart to validate your sandbox setup in minutes and see the core workflow end‑to‑end before wiring the API into checkout or fulfillment.

Visual flow

flowchart LR
  Quote["Get Quote"]
  Generate["Generate Label"]
  Track["Track Shipment"]

  Quote --> Generate --> Track

Before you begin

Create a sandbox account and token (see Auth & Environments).
Choose a carrier to quote. Note: The rate endpoint supports one carrier per request.

Step 1 — Quote rates

Description

Retrieve available services and prices for a single carrier based on origin, destination, and package details.

Required parameters

origin (address object)
destination (address object)
packages (array with at least one package)
shipment (object with type and carrier)

Optional parameters

settings (currency, comments)
customsSettings (international shipments)
shipment.service (quote a specific service only)

curl --request POST \
  --url https://api-test.envia.com/ship/rate/ \
  --header "Authorization: Bearer $ENVIA_SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "origin": {
      "name": "Warehouse MX",
      "phone": "+52 8180000000",
      "street": "Av. Benito Juarez",
      "city": "Monterrey",
      "state": "NL",
      "country": "MX",
      "postalCode": "64060"
    },
    "destination": {
      "name": "Luis Perez",
      "phone": "+52 5511111111",
      "street": "Insurgentes Sur",
      "city": "Ciudad de Mexico",
      "state": "CMX",
      "country": "MX",
      "postalCode": "03100"
    },
    "packages": [
      {
        "type": "box",
        "content": "T-shirts",
        "amount": 1,
        "declaredValue": 1200,
        "lengthUnit": "CM",
        "weightUnit": "KG",
        "weight": 2.5,
        "dimensions": {
          "length": 30,
          "width": 20,
          "height": 10
        }
      }
    ],
    "shipment": {
      "type": 1,
      "carrier": "fedex"
    }
  }'

Response example

{
  "meta": "rate",
  "data": [
    {
      "carrier": "fedex",
      "service": "ground",
      "serviceDescription": "FedEx Ground",
      "deliveryEstimate": "3-5 business days",
      "deliveryDate": {
        "date": "2025-10-11",
        "timeUnit": "days",
        "dateDifference": 3
      },
      "totalPrice": "185.20",
      "currency": "MXN"
    }
  ]
}

Step 2 — Create a shipping label

Description

Purchase a label using the selected carrier service. This returns a tracking number and label URL.

Required parameters

origin
destination
packages
shipment (must include carrier and service)

Optional parameters

settings (currency, comments)
customsSettings (international shipments)
packages[].additionalServices (insurance, COD, signature)

curl --request POST \
  --url https://api-test.envia.com/ship/generate/ \
  --header "Authorization: Bearer $ENVIA_SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "origin": {
      "name": "Warehouse MX",
      "phone": "+52 8180000000",
      "street": "Av. Benito Juarez",
      "city": "Monterrey",
      "state": "NL",
      "country": "MX",
      "postalCode": "64060"
    },
    "destination": {
      "name": "Luis Perez",
      "phone": "+52 5511111111",
      "street": "Insurgentes Sur",
      "city": "Ciudad de Mexico",
      "state": "CMX",
      "country": "MX",
      "postalCode": "03100"
    },
    "packages": [
      {
        "type": "box",
        "content": "T-shirts",
        "amount": 1,
        "declaredValue": 1200,
        "lengthUnit": "CM",
        "weightUnit": "KG",
        "weight": 2.5,
        "dimensions": {
          "length": 30,
          "width": 20,
          "height": 10
        }
      }
    ],
    "shipment": {
      "type": 1,
      "carrier": "fedex",
      "service": "ground"
    }
  }'

Response example

{
  "meta": "generate",
  "data": [
    {
      "carrier": "fedex",
      "service": "ground",
      "shipmentId": 987654,
      "trackingNumber": "123456789MX",
      "trackUrl": "https://tracking.envia.com/123456789MX",
      "label": "https://files.envia.com/labels/123456789MX.pdf",
      "totalPrice": 185.2,
      "currency": "MXN"
    }
  ]
}

Step 3 — Track the shipment

Description

Retrieve status updates for one or more tracking numbers.

Required parameters

trackingNumbers (array)

curl --request POST \
  --url https://api-test.envia.com/ship/generaltrack/ \
  --header "Authorization: Bearer $ENVIA_SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"trackingNumbers": ["123456789MX"]}'

Response example

{
  "meta": "track",
  "data": [
    {
      "trackingNumber": "123456789MX",
      "status": "In transit",
      "carrier": "fedex",
      "events": [
        {
          "timestamp": "2025-10-08T12:30:00Z",
          "location": "Monterrey, MX",
          "description": "Shipment picked up"
        },
        {
          "timestamp": "2025-10-09T17:15:00Z",
          "location": "San Luis Potosi, MX",
          "description": "In transit"
        }
      ]
    }
  ]
}

Errors & troubleshooting

401 Unauthorized

Ensure the Authorization: Bearer token belongs to the same environment (sandbox vs production) as the base URL.

422 Validation errors

Validate address fields with the Queries API (countries, states, cities, postal codes). Some countries require a different city/postal structure.

Empty rate results

Confirm you are passing a single carrier per request and that the carrier supports the lane and package type you submitted.

Sandbox vs production notes

Sandbox base URL: https://api-test.envia.com/
Production base URL: https://api.envia.com/
Use separate tokens for each environment; tokens are not interchangeable.

Next steps

Explore the full Core Workflow guide for pickups, cancellations, and webhooks.
Review Auth & Environments for production readiness.