Guides
Start typing to search…

Core Workflow

Build the full shipping flow: rates → labels → tracking → pickups → cancels → webhooks.

Summary

This guide walks through the core Shipping API workflow from quoting a rate to receiving webhook updates.

Use Case

Use this as your production checklist when you need to orchestrate fulfillment, pickups, and post‑purchase tracking in a single integration.

Visual overview

1. Quote rates

Get Rates (Quote shipping options)

2. Create labels

Generate Label (Create shipment)

3. Track shipments

Track Shipment

4. Schedule pickups

Schedule Pickup

5. Cancel shipments

Cancel Shipment

6. Webhooks

Track via Webhooks (Async updates)

1. Quote rates (POST /ship/rate/)

Description

Retrieve available services and prices for a single carrier.

Required parameters

FieldTypeNotes
originobjectSender address (name, phone, street, city, state, country, postalCode).
destinationobjectRecipient address (name, phone, street, city, state, country, postalCode).
packagesarrayAt least one package with weight, dimensions, and declared value.
shipmentobjectMust include type and carrier.

Optional parameters

FieldTypeNotes
shipment.servicestringQuote only a specific carrier service.
settingsobjectCurrency and comments.
customsSettingsobjectDuties/export settings for international lanes.
curl --request POST \
  --url https://api.envia.com/ship/rate/ \
  --header "Authorization: Bearer $ENVIA_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",
      "totalPrice": "185.20",
      "currency": "MXN"
    }
  ]
}

Errors & troubleshooting

Empty rates

Confirm you are submitting one carrier per request and that the carrier supports the lane and package type.

422 Validation

Use Queries API endpoints to validate country/state/city/postal inputs before quoting.

Sandbox vs production notes

2. Create labels (POST /ship/generate/)

Description

Purchase the label using the selected carrier service and receive tracking details.

Required parameters

FieldTypeNotes
originobjectSender address fields required by carrier.
destinationobjectRecipient address fields required by carrier.
packagesarrayPackage details including weight and dimensions.
shipmentobjectMust include carrier and service.

Optional parameters

FieldTypeNotes
packages[].additionalServicesarrayInsurance, COD, signature.
settingsobjectCurrency or internal comments.
curl --request POST \
  --url https://api.envia.com/ship/generate/ \
  --header "Authorization: Bearer $ENVIA_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"
    }
  ]
}

Errors & troubleshooting

402 Payment Required

Ensure your production balance is funded before purchasing labels.

Validation errors

Required fields vary by country. Validate address fields using Queries and Geocodes APIs.

Sandbox vs production notes

Sandbox labels are not valid for carrier pickup or delivery.

3. Track shipments (POST /ship/generaltrack/)

Description

Retrieve the latest tracking status and event history for one or more shipments.

Required parameters

FieldTypeNotes
trackingNumbersarrayOne or more tracking numbers.
curl --request POST \
  --url https://api.envia.com/ship/generaltrack/ \
  --header "Authorization: Bearer $ENVIA_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"
        }
      ]
    }
  ]
}

Errors & troubleshooting

No tracking events

Some carriers update status only after the first scan. Try again after pickup or line‑haul.

Sandbox vs production notes

Use sandbox tracking numbers for test flows; production numbers show live carrier events.

4. Schedule pickups (POST /ship/pickup/)

Description

Request a carrier pickup for one or more tracking numbers.

Required parameters

FieldTypeNotes
originobjectPickup address and contact details.
shipment.pickupobjectDate, time window, weight, and tracking numbers.
shipment.carrierstringCarrier name.

Optional parameters

FieldTypeNotes
shipment.pickup.instructionsstringSpecial pickup instructions.
curl --request POST \
  --url https://api.envia.com/ship/pickup/ \
  --header "Authorization: Bearer $ENVIA_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"
    },
    "shipment": {
      "type": 1,
      "carrier": "fedex",
      "pickup": {
        "weightUnit": "KG",
        "totalWeight": 2.5,
        "totalPackages": 1,
        "date": "2025-10-10",
        "timeFrom": 10,
        "timeTo": 16,
        "carrier": "fedex",
        "trackingNumbers": ["123456789MX"],
        "instructions": "Ring the loading dock bell"
      }
    }
  }'

Response example

{
  "meta": "pickup",
  "data": {
    "carrier": "fedex",
    "confirmation": "PKP-2025-001",
    "status": "scheduled",
    "date": "2025-10-10",
    "timeFrom": 10,
    "timeTo": 16
  }
}

Errors & troubleshooting

Pickup not available

Some carriers require pickup requests to be created before a cutoff time or only on business days.

Sandbox vs production notes

Sandbox pickups are simulated and should not be scheduled with live couriers.

5. Cancel shipments (POST /ship/cancel/)

Description

Void a label and release the carrier charge if cancellation is allowed.

Required parameters

FieldTypeNotes
carrierstringCarrier name.
trackingNumberstringTracking number to cancel.

Optional parameters

FieldTypeNotes
foliostringInternal reference.
ecommerceintegerShop ID if created via a store connection.
curl --request POST \
  --url https://api.envia.com/ship/cancel/ \
  --header "Authorization: Bearer $ENVIA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"carrier": "fedex", "trackingNumber": "123456789MX"}'

Response example

{
  "meta": "cancel",
  "data": {
    "carrier": "fedex",
    "service": "ground",
    "trackingNumber": "123456789MX",
    "balanceReturned": true,
    "balanceReturnDate": "2025-10-10 12:31:00"
  }
}

Errors & troubleshooting

Cancellation window expired

Some carriers only allow cancellations prior to first scan or within a short window after label creation.

Sandbox vs production notes

In production, cancelled labels may take time to reflect in your balance.

6. Webhooks (Queries API)

Description

Register webhooks to receive tracking and shipment events without polling.

Required parameters

FieldTypeNotes
type_idintegerWebhook type ID (from GET /webhook-types).
urlstringPublic HTTPS endpoint to receive events.
activeinteger1 = active, 0 = inactive.

Optional parameters

FieldTypeNotes
NoneWebhook creation is minimal; update later with PUT /webhooks/{webhook_id}.
curl --request POST \
  --url https://queries.envia.com/webhooks \
  --header "Authorization: Bearer $ENVIA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "type_id": 3,
    "url": "https://example.com/webhooks/envia",
    "active": 1
  }'

Response example

{
  "meta": "webhook_created",
  "data": {
    "id": 4421,
    "type": "tracking.updated",
    "url": "https://example.com/webhooks/envia",
    "active": 1
  }
}

Errors & troubleshooting

Webhook delivery failures

Ensure your endpoint responds with a 2xx status within 5 seconds. Log and retry failed deliveries.

Sandbox vs production notes

Updated 2 days ago