---
title: "Create a Commercial Invoice"
method: POST
path: "/ship/commercial-invoice"
tags: ["Commercial Invoice"]
---

# Create a Commercial Invoice

`POST /ship/commercial-invoice`

## Request

- Base URL: `https://api-test.envia.com`
- URL: `https://api-test.envia.com/ship/commercial-invoice`
- Auth: HTTP bearer

Generate an Envia commercial invoice PDF for an international label you already created.

**When to use:** After `/ship/generate`, when the carrier or destination needs a commercial invoice. FedEx and DHL Express return their own invoice in `data[].additionalFiles` of `/ship/generate`, so this call is not needed for them. For UPS (`ups2`), call it right after the label.

**Prerequisites:**
- Valid JWT authentication token (Bearer)
- A label that belongs to your account and is not cancelled (`shipment.carrier` + `shipment.trackingNumber`). Otherwise error `1127` is returned.
- Every package must include `amount`, `declaredValue`, `totalWeight`, `cost`, `cubicMeters` and `items`

**Key behaviors:**
- The PDF is built only from this request. Nothing is copied from the `/ship/generate` request.
- The invoice is always in English. For FedEx, DHL, UPS and most carriers, amounts are printed in USD. Send `settings.currency: "USD"` when prices are in USD; otherwise prices are converted from `packages[].currency`.
- `price` is a unit price. Line subtotal = price × quantity × package `amount`.
- If `customsSettings.exportReason` is omitted, the invoice prints "Sample". Send `sale` for commercial shipments.
- The "Tax ID" lines print `origin.taxId` / `destination.taxId`, not `identificationNumber`.
- No charge is applied. Calling it again for the same tracking number replaces the PDF at the same URL (and, for UPS, sends it to UPS again).
- The PDF URL does not expire. It is also returned later as `bol_file` by the Queries API (`GET /guide/{tracking_number}`).

## Request body

- object
  - `origin` object, required: Origin address information
    - `name` string, required: Name of the person
    - `company` string: Name of the company or business
    - `email` string, email: Email address
    - `phone_code` string: Country phone code
    - `phone` string, required: Phone number
    - `street` string, required: Street address
    - `number` string: Street number
    - `district` string: District or neighborhood
    - `city` string, required: City name
    - `state` string, required: State or province code (e.g., NL, TX, QC)
    - `country` string, required: ISO 3166-1 alpha-2 country code (e.g., MX, US, CO)
    - `postalCode` string, required: Zipcode value
    - `reference` string: Reference information for delivery
    - `address_id` integer: Unique identifier of a previously saved address in your Envia account. When provided, the saved address data is used and you can omit the other address fields. Retrieve saved address IDs from the Queries API (Get All Addresses).
    - `identificationNumber` string: Tax identification number. Not printed on the Envia invoice; use `taxId` for that.
    - `category` integer: Address category
    - `taxId` string: Tax ID printed on the Envia commercial invoice. Leave it empty if you do not want a tax ID printed.
  - `destination` object, required: Destination address information
    - `name` string, required: Name of the person
    - `company` string: Name of the company or business
    - `email` string, email: Email address
    - `phone_code` string: Country phone code
    - `phone` string, required: Phone number
    - `street` string, required: Street address
    - `number` string: Street number
    - `district` string: District or neighborhood
    - `city` string, required: City name
    - `state` string, required: State or province code (e.g., NL, TX, QC). Retrieve valid codes from the Queries API (Get States by Country).
    - `country` string, required: ISO 3166-1 alpha-2 country code (e.g., MX, US, CO)
    - `postalCode` string, required: Zipcode value
    - `reference` string: Reference information for delivery
    - `address_id` integer: Unique identifier of a previously saved address in your Envia account. When provided, the saved address data is used and you can omit the other address fields. Retrieve saved address IDs from the Queries API (Get All Addresses).
    - `identificationNumber` string: Tax identification number. Not printed on the Envia invoice; use `taxId` for that.
    - `category` integer: Address category
    - `taxId` string: Tax ID printed on the Envia commercial invoice. Leave it empty if you do not want a tax ID printed.
  - `shipment` object, required: Shipment information
    - `carrier` string, required: Carrier name, exactly as returned by the rate response (for example `fedex`, `dhl`, `ups2`). Required: the tracking number is looked up under this carrier.
    - `trackingNumber` string, required: Tracking number generated when making the shipment
    - `orderReference` string: Your order number. Printed as "Order number" on the invoice.
  - `packages` object[], required: List of packages
    - `amount` integer, required: Number of identical packages. Item quantities are multiplied by this value.
    - `declaredValue` number, required: Declared value of the package
    - `totalWeight` number, required: Total package weight. Printed in kg.
    - `weightUnit` 'KG' | 'LB': Unit of `totalWeight`. LB is converted to kg. Default: KG.
    - `cost` number, required: Shipping cost of the package. Send 0 if you do not want to declare it.
    - `cubicMeters` number, required: Package volume in cubic meters. Send 0 if you do not use it.
    - `currency` string: Currency of the package and item prices. Required when `settings.currency` is missing or is not USD; the amounts are converted to USD from this currency.
    - `items` object[], required: List of items in the package
      - `description` string, required: Description of the item, in English. If empty, "Product" is printed.
      - `productCode` string, required: HS code of the item. `hsCode` is accepted as an alias. Printed as sent.
      - `countryOfManufacture` string: Country where the item was made (ISO 3166-1 alpha-2). Printed as the item's origin country. The dispatch country comes from `origin.country`.
      - `quantity` integer, required: Units of this item per package. Decimals are dropped. The invoice prints quantity × package `amount`.
      - `price` number, required: Unit price of the item, printed with 2 decimals. Subtotal = price × quantity × package `amount`.
  - `customsSettings` object, required: Customs settings for international shipments
    - `dutiesPaymentEntity` 'sender' | 'recipient' | 'envia_guaranteed', required: Who pays duties and taxes. `recipient` prints incoterm DAP; `sender` and `envia_guaranteed` print DDP.
    - `exportReason` 'sale' | 'gift' | 'sample' | 'return' | 'personal_effects': Export reason, printed as "Purpose of shipment". If omitted, the invoice prints "Sample"; send `sale` for commercial shipments.
    - `itn` string: US AES Internal Transaction Number. Printed as "Export Declaration / Customs Reference No."
  - `settings` object: Invoice options
    - `currency` string: Send `USD` when prices are already in USD; amounts are printed as sent. Any other value, or no value, converts amounts to USD using `packages[].currency`.
    - `printSize` 'PAPER_4X6' | 'STOCK_4X6' | 'PAPER_LETTER': `PAPER_4X6` or `STOCK_4X6` produces a 4x6 invoice. Any other value produces a letter-size invoice. The output is always PDF.

## Response `200`

Commercial invoice created successfully

- object
  - `meta` string: Always `billoflading`
  - `data` object
    - `carrier` string: Carrier of the label
    - `trackingNumber` string: Associated tracking number
    - `billOfLading` string: Direct URL of the commercial invoice PDF. It does not expire.

## Changes

- **2026-11-03** `3d23462f7fe2`: 5 breaking, 8 info
  - added the new required request property `packages/items/amount`
  - added the new required request property `packages/items/cost`
  - added the new required request property `packages/items/cubicMeters`
  - added the new required request property `packages/items/declaredValue`
  - …9 more

[Operation history](https://skmtc.dev/envia/apis/envia-shipping-api-complete-documentation/changes/ship/commercial-invoice/post.md)

---

[API](https://skmtc.dev/envia/apis/envia-shipping-api-complete-documentation.md) - [All operations](https://skmtc.dev/envia/apis/envia-shipping-api-complete-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/envia/apis/envia-shipping-api-complete-documentation/revisions/3d23462f7fe2?raw)