---
updatedAt: 2026-10-28T22:04:38.000Z
agentTools:
  projectIndex: https://docs.envia.com/llms.txt
---

# FAQs

Find answers to the most common questions about integrating with the Envia Shipping, Queries, and Geocodes APIs. Questions are organized by topic — use the navigation below to jump to what you need.

## Find your answer

Not sure where to start? Use this decision tree:

| Symptom                                           | Go to                                                          |
| :------------------------------------------------ | :------------------------------------------------------------- |
| Getting address or "no coverage" errors           | [Addresses & location data](#addresses--location-data)         |
| Authentication or 401 errors                      | [Authentication & environments](#authentication--environments) |
| Not sure which carrier or service to use          | [Carriers & services](#carriers--services)                     |
| Unexpected rate results or pricing questions      | [Rates & pricing](#rates--pricing)                             |
| Label creation fails or returns unexpected data   | [Labels & shipments](#labels--shipments)                       |
| Pickup scheduling or pickup vs generate questions | [Pickups](#pickups)                                            |
| Tracking not updating or webhook issues           | [Tracking & webhooks](#tracking--webhooks)                     |
| International shipment or customs questions       | [International shipping](#international-shipping)              |
| None of the above                                 | [Getting help](#getting-help)                                  |

***

## Self-serve diagnostic tools

Before opening a support ticket, use these tools to diagnose issues yourself. They cover the majority of integration problems.

| Tool                            | URL                                                             | What it tells you                                                             |
| :------------------------------ | :-------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| **Validate a postal code**      | `GET https://geocodes.envia.com/zipcode/{country}/{postalCode}` | Correct city, state code, and locality for any postal code — no auth required |
| **Get state codes**             | `GET https://queries.envia.com/state?country_code={XX}`         | Envia's 2-letter state codes for a country                                    |
| **Check address structure**     | `GET https://queries.envia.com/address-structure/{country}`     | Required fields and validation rules per country                              |
| **List carriers for a country** | `GET https://queries.envia.com/carrier?country_code={XX}`       | Available carriers and their capabilities                                     |
| **Test a webhook**              | `POST /ship/webhook/test/`                                      | Sends a test payload to verify your webhook endpoint                          |

<Callout icon="💡" theme="default">
  **Tip:** The Geocodes API requires no authentication and is the fastest way to validate addresses during development.
</Callout>

***

## Authentication & environments

<Accordion title="I'm getting a 401 Unauthorized error">
  This means your API token is missing, expired, or does not match the environment you are calling.

  **Checklist:**
  1. Verify the `Authorization: Bearer <token>` header is present in your request
  2. Confirm the token belongs to the **same environment** as the base URL:
     - Sandbox tokens → `api-test.envia.com` / `queries.test.envia.com`
     - Production tokens → `api.envia.com` / `queries.envia.com`
  3. Check that the token has not been revoked in **Dashboard → Desarrolladores → Acceso de API**

  Tokens are not interchangeable between environments. See [API Authentication](https://docs.envia.com/docs/authentication) for setup details.
</Accordion>

<Accordion title="How do I switch from sandbox to production?">
  1. Create a production account at [accounts.envia.com/signup](https://accounts.envia.com/signup)
  2. Generate a production API key in the production dashboard
  3. Replace your base URLs (`api-test` → `api`, `queries.test` → `queries`)
  4. Use separate webhook URLs for each environment

  See the full [Production Readiness Checklist](https://docs.envia.com/docs/production-checklist) for every item to verify before going live.
</Accordion>

<Accordion title="Does the Geocodes API require authentication?">
  No. The Geocodes API has a single production URL (`https://geocodes.envia.com/`) and does not require a Bearer token. You can call it directly from a browser or frontend application.
</Accordion>

***

## Addresses & location data

<Accordion title="Why am I getting 'no coverage' or 'invalid address' errors?">
  The most common cause is **incorrect state codes**. Envia uses its own 2-letter state codes, which may differ from codes used by other platforms (Shopify, WooCommerce, ISO 3166-2, etc.).

  For example, in Argentina:

  | Province | Envia code | Shopify code | ISO 3166-2 |
  | :------- | :--------: | :----------: | :--------: |
  | Córdoba | `CB` | `X` | `AR-X` |
  | Ciudad Autónoma de Buenos Aires | `DF` | `C` | `AR-C` |
  | Tierra del Fuego | `TF` | `V` | `AR-V` |

  **Fix:** Always retrieve Envia's state codes from the Queries API — do not reuse codes from other platforms.

  ```
  GET https://queries.envia.com/state?country_code=AR
  ```

  **[Full reference → Get States by Country](https://docs.envia.com/reference/states-by-country)**
</Accordion>

<Accordion title="How do I validate a postal code before quoting?">
  Use the Geocodes API — no authentication required:

  ```
  GET https://geocodes.envia.com/zipcode/{country}/{postalCode}
  ```

  The response returns the correct city, state code, and locality for that postal code. Use these values in your rate and label requests to avoid address-related errors.

  **[Full reference → Validate Zip Code](https://docs.envia.com/reference/validate-zip-code)**
</Accordion>

<Accordion title="Do address field requirements change by country?">
  Yes. Required fields, formats, and validation rules vary by country. Some countries require a `district` or `locality` field; others do not. Use the address structure endpoint to get the exact requirements:

  ```
  GET https://queries.envia.com/address-structure/{country}
  ```

  **[Full reference → Get Address Structure](https://docs.envia.com/reference/country-address-structure)**
</Accordion>

<Accordion title="I get different errors with different carriers for the same address">
  Each carrier validates addresses independently with different strictness levels. Some carriers are strict about state codes, while others rely on postal codes.

  **To avoid issues across all carriers:**
  1. Validate postal codes using the [Geocodes API](https://docs.envia.com/reference/validate-zip-code) to get the canonical state, city, and locality
  2. Use Envia's 2-letter state codes from the [Queries API](https://docs.envia.com/reference/states-by-country) — not codes from external platforms
  3. Check the [address structure](https://docs.envia.com/reference/country-address-structure) for the destination country to ensure all required fields are present
</Accordion>

***

## Carriers & services

<Accordion title="How do I find which carriers are available for my route?">
  Use the Queries API to get carriers by country:

  ```
  GET https://queries.envia.com/carrier?country_code=AR
  ```

  Replace `AR` with any supported 2-letter country code (`MX`, `BR`, `CO`, `CL`, `US`, `CA`, `ES`, `IN`, etc.).

  For a real-time check that accounts for your account configuration, use the rate endpoint directly — it only returns carriers and services that can actually fulfill the shipment.

  **[Full reference → Get Carriers by Country](https://docs.envia.com/reference/carriers-by-country)**
</Accordion>

<Accordion title="Can I filter rates by a specific carrier?">
  Yes. Add the `carrier` field to the `shipment` object in your rate request:

  ```json
  {
    "shipment": {
      "carrier": "correoArgentino",
      "type": 1
    }
  }
  ```

  Omit the `carrier` field to get rates from all available carriers for the route. The rate endpoint accepts **one carrier per request** — to compare multiple carriers, call it once per carrier.
</Accordion>

<Accordion title="What shipment types are available?">
  The `shipment.type` field accepts these values:

  | Type | Value | Description |
  | :--- | :---: | :---------- |
  | Parcel | `1` | Standard package shipments |
  | LTL (Less than Truckload) | `2` | Freight shipments that share truck space |

  Most carriers support **Parcel (type 1) only**. Sending an unsupported type returns an error. Check the [Supported Carriers](https://docs.envia.com/docs/supported-carriers) page — the **LTL** column shows which carriers support LTL.

  **FTL (Full Truckload)** shipments are currently managed through the [cargo.envia.com](https://cargo.envia.com) platform and are not yet available via API.
</Accordion>

<Accordion title="How do I know which shipment type a carrier supports?">
  Use the Queries API to get carriers filtered by shipment type:

  ```
  GET https://queries.envia.com/available-carrier/{country}/{international}/{shipment_type_id}
  ```

  **[Full reference → Get Available Carriers (Detailed)](https://docs.envia.com/reference/available-couriers-detailed)**
</Accordion>

***

## Rates & pricing

<Accordion title="Why am I getting empty rate results?">
  Empty rate results usually mean one of:

  1. **The carrier does not serve the route** — Verify carrier availability with the [Queries API](https://docs.envia.com/reference/carriers-by-country)
  2. **Invalid address data** — Validate postal codes with the [Geocodes API](https://docs.envia.com/reference/validate-zip-code) and state codes with the [Queries API](https://docs.envia.com/reference/states-by-country)
  3. **Unsupported package dimensions or weight** — Each carrier has its own limits; check the [Supported Carriers](https://docs.envia.com/docs/supported-carriers) page
  4. **Wrong shipment type** — Confirm the carrier supports the `shipment.type` value you are sending (most only support `1` for parcel)
</Accordion>

<Accordion title="Why do rates differ between sandbox and production?">
  Sandbox returns **simulated rates** for testing purposes. Production returns **real rates** from carriers based on your account's negotiated pricing, carrier contracts, and current surcharges. Always do final price validation in production.
</Accordion>

<Accordion title="Can I get rates in a specific currency?">
  Yes. Include the `currency` field in the `settings` object of your rate request:

  ```json
  {
    "settings": {
      "currency": "USD"
    }
  }
  ```

  If omitted, rates are returned in the default currency for your account's country.
</Accordion>

***

## Labels & shipments

<Accordion title="The Shipping API returned HTTP 200 but the response contains an error">
  This is a known behavior of the Shipping API. Some errors return HTTP `200` with `"meta": "error"` in the body instead of a 4xx status code.

  **Always check the `meta` field** in every Shipping API response — do not rely solely on the HTTP status code.

  ```json
  {
    "meta": "error",
    "error": {
      "code": 400,
      "description": "Invalid Option",
      "message": "The origin.postalCode field is required."
    }
  }
  ```

  See [Error Response Formats](https://docs.envia.com/docs/error-codes) for the full error shapes returned by each API and a normalization helper.
</Accordion>

<Accordion title="How do I cancel a label?">
  Use the cancel endpoint with the `shipmentId` returned when the label was created:

  ```
  POST https://api.envia.com/ship/cancel/
  ```

  Cancelling a label **before the carrier scans it** triggers an automatic refund to your account balance. Once a carrier has scanned the package, cancellation may no longer be possible.

  **[Full reference → Cancel Shipment](https://docs.envia.com/reference/cancel-shipment)**
</Accordion>

<Accordion title="Can I create a label with multiple packages?">
  Yes. Include multiple objects in the `packages` array of your label request. Each package gets its own tracking number in the response.

  See the [Shipping Multiple Packages](https://docs.envia.com/docs/shipping-multiple-packages) workflow guide for a complete example.
</Accordion>

***

## Pickups

<Accordion title="How does pickup work? Does every carrier support it?">
  Pickup behavior varies by carrier — some support standalone scheduling, others schedule automatically during label creation, and some only accept drop-offs at branches. Use **[Get Carrier Actions](https://docs.envia.com/reference/carrier-actions)** to check what each carrier supports.

  **[Full guide → Pickups concept page](https://docs.envia.com/docs/pickups)**
</Accordion>

<Accordion title="Can I schedule a pickup for multiple tracking numbers at once?">
  Yes. The `POST /ship/pickup/` endpoint accepts multiple tracking numbers in a single request. All tracking numbers must belong to the same carrier and originate from the same address. For high-volume operations, see the **[Pickup & Manifest Workflow](https://docs.envia.com/docs/pickup-manifest-workflow)**.
</Accordion>

***

## Tracking & webhooks

<Accordion title="How do I track a shipment?">
  Use the tracking endpoint with one or more tracking numbers:

  ```
  POST https://api.envia.com/ship/generaltrack/
  ```

  ```json
  {
    "trackingNumbers": ["7072262094"]
  }
  ```

  The response includes the current status, carrier name, and a chronological list of events.

  **[Full reference → Track Shipments](https://docs.envia.com/reference/track-shipments)**
</Accordion>

<Accordion title="My webhook endpoint is not receiving events">
  **Checklist:**
  1. Your endpoint URL must be publicly reachable via **HTTPS** (not HTTP, not localhost)
  2. Your endpoint must respond with a **2xx status code within 5 seconds** — slower responses may be treated as failures
  3. Verify the webhook is registered and active using `GET https://queries.envia.com/webhooks`
  4. Confirm you registered **separate webhook URLs** for sandbox and production
  5. Test delivery with the [Test Webhook](https://docs.envia.com/reference/test-webhook-endpoint) endpoint to isolate whether the issue is in registration or in your endpoint

  See the [Webhooks Guide](https://docs.envia.com/docs/webhooks) for setup and troubleshooting details.
</Accordion>

<Accordion title="How do I handle duplicate webhook deliveries?">
  Webhooks may be delivered more than once (e.g., due to network retries). Implement **idempotency** by tracking the `shipmentId` and event type you have already processed. If you receive a duplicate, acknowledge it with a 2xx response but skip reprocessing.
</Accordion>

***

## International shipping

<Accordion title="What additional data is required for international shipments?">
  International labels need:

  - An `items` array in every package, with description, HS code (`productCode`), quantity, **unit** price and country of manufacture (see [HS Codes](https://docs.envia.com/docs/hs-codes))
  - **Declared value** per package
  - A `customsSettings` object with `dutiesPaymentEntity` and `exportReason`
  - A **commercial invoice** for some carriers (see the next question)

  See the [International Shipping Workflow](https://docs.envia.com/docs/international-shipping-workflow) for a complete step-by-step example.
</Accordion>

<Accordion title="Do I need to create a commercial invoice separately?">
  It depends on the carrier:

  - **FedEx** and **DHL Express** return the commercial invoice in `data[].additionalFiles` of the label response. No extra call is needed.
  - **UPS** (`ups2`) does not return one. Call [Create Commercial Invoice](https://docs.envia.com/reference/create-commercial-invoice) right after the label.
  - For other carriers, call the endpoint when the carrier or destination requires an invoice.

  The endpoint needs the label's tracking number, so always call it after `/ship/generate/`. See the [Commercial Invoice guide](https://docs.envia.com/docs/commercial-invoice) for every field.
</Accordion>

<Accordion title="How do I classify my products with HS codes?">
  Use the HS code classification utility to get the correct code for your product:

  **[Full reference → Classify HS Code](https://docs.envia.com/reference/classify-hs-code)**

  For a detailed explanation of how HS codes work and why they matter, see the [HS Codes guide](https://docs.envia.com/docs/hs-codes).
</Accordion>

***

## Common mistakes

These are the issues that trip up most integrators. Addressing them early saves significant debugging time.

|  #  | Mistake                                                                             | Impact                                               | Fix                                                                         |
| :-: | :---------------------------------------------------------------------------------- | :--------------------------------------------------- | :-------------------------------------------------------------------------- |
|  1  | Using state codes from Shopify, WooCommerce, or ISO 3166-2 instead of Envia's codes | "No coverage" errors, failed labels                  | Always fetch state codes from `GET /state?country_code={XX}`                |
|  2  | Not checking the `meta` field in Shipping API responses                             | Silent failures — HTTP 200 with an error in the body | Check `meta === "error"` on every Shipping API response                     |
|  3  | Using a sandbox token with a production URL (or vice versa)                         | 401 Unauthorized                                     | Match token environment to base URL                                         |
|  4  | Sending multiple carriers in a single rate request                                  | Unexpected results or errors                         | The rate endpoint accepts **one carrier per request**                       |
|  5  | Assuming address fields are the same across countries                               | Validation errors in specific countries              | Use `GET /address-structure/{country}` to get country-specific requirements |
|  6  | Not handling the three different error response formats                             | Missed errors, broken error handling                 | See [Error Response Formats](https://docs.envia.com/docs/error-codes) for a normalization helper    |
|  7  | Webhook endpoint responds too slowly or over HTTP                                   | Missed events, delivery failures                     | Ensure HTTPS and respond with 2xx within 5 seconds                          |

***

## Getting help

### 1. Search the docs

Most questions are answered in the documentation. Use the search bar at the top of this page, or explore these key resources:

<Cards>
  <Card title="Error Response Formats" href="/docs/error-codes" icon="fa-exclamation-triangle">
    How each API returns errors, with a normalization helper.
  </Card>

  <Card title="Core Workflow" href="/docs/core-workflow" icon="fa-route">
    The full shipping flow from quote to delivery with code examples.
  </Card>

  <Card title="Supported Carriers" href="/docs/supported-carriers" icon="fa-truck">
    Carrier capabilities, label formats, and shipment type support.
  </Card>

  <Card title="Production Checklist" href="/docs/production-checklist" icon="fa-clipboard-check">
    Everything to verify before going live.
  </Card>
</Cards>

### 2. Open a support ticket

If you cannot find an answer in the docs, open a ticket with the following information for the fastest resolution:

* **Endpoint URL** and HTTP method
* **Full request body** (redact sensitive data)
* **Full response body** including `carrier_message` if present
* **Timestamp** of the request
* **Environment** (sandbox or production)

**[Open a support ticket →](https://envia.atlassian.net/servicedesk/customer/portal/3/group/3/create/10611)**