Pickups

Pickup scheduling lets you request a carrier driver to collect packages from your location instead of dropping them off at a branch or service point. Pickup behavior varies by carrier — not all carriers support the same pickup methods, and some do not support pickup at all.

Before integrating pickups, always check what each carrier supports using the Queries API.

Pickup capabilities by carrier

Each carrier supports a different combination of pickup capabilities. Use the Get Carrier Actions endpoint to check what a specific carrier supports:

GET https://queries.envia.com/carrier-action/{carrier_name}

The response includes action flags that tell you exactly how pickup works for that carrier:

Some carriers support multiple pickup methods (e.g., both pickup and pickup_on_generate). In these cases, choose the method that fits your workflow.

Example: Check carrier pickup capabilities

curl --request GET \
  --url "https://queries.envia.com/carrier-action" \
  --header "Authorization: Bearer $ENVIA_TOKEN"

Example response

[
  { "id": 184, "name": "fedex", "country_code": "MX", "action_id": 5, "action_name": "pickup" },
  { "id": 185, "name": "fedex", "country_code": "MX", "action_id": 1, "action_name": "rate" },
  { "id": 186, "name": "fedex", "country_code": "MX", "action_id": 2, "action_name": "generate" }
]

In this example, FedEx has the pickup action — meaning you should use POST /ship/pickup/ after generating labels.

Two pickup methods

Envia provides two ways to handle pickups. Which one to use depends on the carrier's supported actions.

Method 1: Standalone pickup (POST /ship/pickup/)

Use this method for carriers with the pickup action flag. This is the most common method and works with most carriers.

How it works:

1. Generate your shipping labels first (POST /ship/generate/)
2. Call POST /ship/pickup/ with the carrier name, tracking numbers, and your preferred date/time window
3. Envia calls the carrier's pickup scheduling API
4. You receive a pickup confirmation number

Characteristics:

• Requires existing tracking numbers from generated labels
• Validates pickup requirements (date, time window, packages, weight)
• Charges a pickup fee to your account
• Returns a confirmation number from the carrier

curl --request POST \
  --url "https://api.envia.com/ship/pickup/" \
  --header "Authorization: Bearer $ENVIA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "carrier": "fedex",
    "pickupDate": "2026-04-15",
    "pickupTimeStart": "09:00",
    "pickupTimeEnd": "14:00",
    "pickupAddress": {
      "name": "Carlos Mendoza",
      "company": "Almacén Central",
      "phone": "+52 8181234567",
      "email": "[email protected]",
      "street": "Av. Ruiz Cortines 2500",
      "number": "100",
      "city": "San Pedro Garza Garcia",
      "state": "NL",
      "country": "MX",
      "postalCode": "66260"
    },
    "trackingNumbers": [
      "794644790138",
      "794644790149"
    ]
  }'

Example response

{
  "meta": "pickup",
  "data": {
    "carrier": "fedex",
    "confirmation": "PKP-2026-04150001",
    "status": "scheduled",
    "date": "2026-04-15",
    "timeFrom": 9,
    "timeTo": 14
  }
}

Full endpoint reference → Schedule a Carrier Pickup

Method 2: Pickup on generate (shipment.pickup)

Use this method for carriers with the pickup_on_generate action flag. With these carriers, pickup is automatically scheduled when you create the label — no separate API call needed.

How it works:

1. Include the shipment.pickup object in your Generate request (POST /ship/generate/)
2. The carrier schedules the pickup as part of label creation
3. The label response includes pickup confirmation

Characteristics:

• No separate pickup API call needed
• Pickup details are sent together with the label request
• The carrier handles pickup scheduling during the generate flow
• No additional pickup fee (included in the shipment cost)

{
  "origin": { ... },
  "destination": { ... },
  "packages": [ ... ],
  "shipment": {
    "type": 1,
    "carrier": "amazon",
    "service": "standard",
    "pickup": {
      "date": "2026-04-15",
      "totalPackages": 2,
      "totalWeight": 5.5
    }
  }
}

Note: The shipment.pickup object is only used by carriers with the pickup_on_generate action. For other carriers, including this object in your Generate request has no effect on pickup scheduling — you still need to call POST /ship/pickup/ separately.

Carriers that require pickup (pickup_mandatory)

Some carriers do not accept drop-offs and require a scheduled pickup for every shipment. These carriers have the pickup_mandatory action flag.

When working with these carriers:

• You must schedule a pickup after generating labels
• Failing to schedule a pickup may result in the shipment not being collected
• Check the carrier's cutoff times and available pickup windows

Carriers without pickup support

Some carriers do not support pickup at all — they only operate through branches or drop-off points. These carriers have no pickup-related action flags.

For these carriers, use the Queries API to look up available branches where you can deliver your packages:

GET https://queries.envia.com/branch?carrier={carrier_name}&country_code={XX}

Decision flow

Use this flow to determine the right pickup method for any carrier:

flowchart TD
    A["Check carrier actions\n(Get Carrier Actions)"] --> B{Has pickup_on_generate?}
    B -- Yes --> C["Include shipment.pickup\nin Generate request"]
    B -- No --> D{Has pickup?}
    D -- Yes --> E["Call POST /ship/pickup/\nafter generating labels"]
    D -- No --> F{Has pickup_mandatory?}
    F -- Yes --> G["Schedule pickup\n(required by carrier)"]
    F -- No --> H["Drop-off / branch only\n(no pickup available)"]
    style A fill:#1873dc,color:#fff
    style C fill:#059669,color:#fff
    style E fill:#059669,color:#fff
    style G fill:#d97706,color:#fff
    style H fill:#dc2626,color:#fff

Comparison table

Important considerations

• Always check carrier actions first. Do not assume a carrier supports a specific pickup method. Use Get Carrier Actions to verify.
• Pickup availability varies by location and time. Carriers have cutoff times, blackout dates, and minimum package requirements that vary by region.
• Multiple tracking numbers in one pickup. When using standalone pickup (POST /ship/pickup/), you can include multiple tracking numbers in a single request — all packages must belong to the same carrier and originate from the same address.
• Pickup fees. Standalone pickups charge a fee to your account balance. Check your balance before scheduling. Pickup-on-generate carriers typically include the pickup cost in the shipping rate.

Related pages

• Schedule a Carrier Pickup — Endpoint reference for POST /ship/pickup/
• Generate Shipping Label — Include shipment.pickup for pickup-on-generate carriers
• Get Carrier Actions — Check which pickup methods a carrier supports
• Pickup & Manifest Workflow — Step-by-step workflow for high-volume pickup with manifests
• Additional Services — Insurance, COD, and other services you can add to shipments