Commercial Invoices

Endpoints relating to Commercial Invoice objects

List commercial invoices

Returns a list of commercial invoices

Request
query Parameters
page
integer >= 1
Default: 1

Page number of the page to retrieve

Example: page=1
per
integer [ 1 .. 100 ]
Default: 20

Count of items in each page. Should be between 1 and 100 (inclusive)

Example: per=20
f.shipment.id
string

The unique id for the shipment.

f.invoice_number
string

Filters results based on the invoice number.

f.involved_party_seller_id
string

Filters results based on the involved party seller ID.

f.involved_party_seller_ref
string

Filters results based on the involved party seller ref.

f.updated_at
string

Filters results with the specified updated_at

f.created_at.gt
string

Filters results updated after the specified date

f.created_at.gte
string

Filters results updated after the specified date, inclusive

f.created_at.lt
string

Filters results updated before the specified date

f.created_at.lte
string

Filters results updated before the specified date, inclusive

Responses
200

Success

Response Schema: application/json
_object
string
self
string
version
integer
object
_object
string
prev
string or null
next
string or null
Array of objects (CommercialInvoice)
get/commercial_invoices
Response samples
application/json

Success

{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/commercial_invoices?page=2&per=10",
  • "version": 3,
  • "data": {
    • "_object": "/api/collections/paginated",
    • "prev": "https://api.flexport.com/commercial_invoices?page=1&per=10",
    • "next": null,
    • "data": [
      • {
        }
      ]
    }
}

Create or update a commercial invoice

Creates a commercial invoice if it does not exist yet, otherwise updates an existing entry.

Optional input fields

  • Party address zip may be omitted for countries and territories without postal codes, such as Hong Kong. It remains required and non-blank where postal codes are used. An existing manufacturer may also be referenced by mid_code without sending an address.
  • Line price_per_unit may be omitted or null. It is calculated from value.amount / quantity.value using 34 significant decimal digits and half-even rounding. This calculation requires a positive whole-number quantity no greater than 2147483647. Supplied prices are preserved.
  • Header currency may be omitted or null when there is at least one line and all lines provide the same value.currency_code. That currency becomes the invoice currency. Empty or mixed-currency lines cannot supply a missing header currency. A supplied header currency is preserved.

Weight rules

  • Weights are optional. Choose the level for each type: header total_gross_weight or line weight; header total_net_weight or line net_weight.
  • You may mix levels for different weight types. Do not supply the same type at both levels.
  • Line net_net_weight may accompany either or both header weights.
  • Header totals must be positive. When supplied, all header and line weights must use the same unit.
  • Every line requires a positive, non-null quantity. Header totals require at least one line, with all line quantities using the same unit.

Header weight allocation

  • Totals are distributed across lines in proportion to their quantities.
  • Allocations use two decimal places, or the header total's precision if greater (for example, 10.005 uses three).
  • Rounding preserves the total. Remainders go to the largest fractional shares, with ties resolved by line order. Small allocations may be zero.

This is an asynchronous operation. Successful response means only that submission is accepted, and the actual result of this operation is reported via webhook. Processing errors are not returned in this response; they are delivered in the failure webhook, which lists the possible errors along with their causes and suggested fixes.

Request
header Parameters
X-Request-ID
required
string <uuid>

A unique identifier for the request. Subsequent requests with the same ID will be rejected.

Example: 7c8cdc41-7e08-4d99-8147-2709ee6c7f6f
X-Webhook-ID
required
string <uuid>

An identifier for webhook correlation, linking the request to webhook notifications

Example: 0122a4bb-b132-407c-9843-3dd60354807d
Request Body schema: application/json
required
invoice_number
required
string

Invoice number on the commercial invoice, typically used for display purposes.

required
Array of objects (CreateCommercialInvoiceLineItem)

Line items for the commercial invoice. Choose the level independently for each weight type: total_gross_weight on the header or weight on the lines, and total_net_weight on the header or net_weight on the lines. Do not supply the same weight type at both levels. Line net_net_weight may accompany either or both header weights. When header weights are supplied, all header and line weights must use the same unit. All weight fields may be omitted. Every line item requires a non-null quantity greater than zero.

Array
document_line_number
integer

Line number on the commercial invoice document.

MoneyCreate (object) or null

Unit price. If omitted or null, calculated as value.amount / quantity.value in value.currency_code, using 34 significant decimal digits and half-even rounding before storage. Calculation requires a positive whole-number quantity no greater than 2147483647. A supplied unit price is preserved, including when it differs from value.amount / quantity.value.

object (MoneyCreate)
required
object (MoneyCreate)
object (MoneyCreate)
required
object (CreateCommercialInvoiceLineItemQuantity)

Total quantity for this line item. Required and non-null; the value must be greater than zero.

container_number
string

Container number associated with this line item.

purchase_order_number
string

Purchase order number associated with this line item.

po_line_item_number
string

Purchase order line item number.

object

Weight including any associated packaging (padding, foam, etc). Cannot be combined with header total_gross_weight. May be combined with header total_net_weight, using the same weight unit.

object (VolumeCreate)
object

Weight excluding packaging. Cannot be combined with header total_net_weight. May be combined with header total_gross_weight, using the same weight unit.

object

Weight excluding packaging, tags, labels, instruction manuals, etc. May be combined with either or both header total_gross_weight and total_net_weight, using the same weight unit.

object (CreateCustomsInvolvedParty)
required
object

A product associated with this line item. This product may be created if it doesn't exist yet, and the product creation feature is enabled for your account.

object or Array of objects

Set of custom key-values specific to the object. The keys are strings and values are arrays of strings. The set of valid keys is always the consignee's list of keys, even if call was made by a different party. Please contact Flexport representative before sending any attributes in this field.

Array of objects (CreateCommercialInvoiceChargeAdjustment)

List of charge adjustments.

object

US CBP special program indicator. Only applicable for US entries.

object

Total gross weight, including packaging. Must be positive. Allocated to lines by quantity without changing the total. Do not provide line weight with this field. Line net_weight and net_net_weight are allowed. All header and line weights must use the same unit.

value
number

Required. Specifies the weight as a float.

unit
string

Required. Unit of measurement. "kg" for kilograms, "lbs" for pounds

Enum: "kg" "lbs"
object

Total net weight, excluding packaging. Must be positive. Allocated to lines by quantity without changing the total. Do not provide line net_weight with this field. Line weight and net_net_weight are allowed. All header and line weights must use the same unit.

value
number

Required. Specifies the weight as a float.

unit
string

Required. Unit of measurement. "kg" for kilograms, "lbs" for pounds

Enum: "kg" "lbs"
Array of objects or null (CreateCustomsInvolvedParty)

Optional list of parties involved in the commercial transaction.

Array
object

Address of the involved party. Required when creating new network entities. Also required when matching existing entities unless external_ref or mid_code is provided. Postal code (zip) may be omitted for countries and territories without a postal-code system, including Hong Kong (HK), Macao (MO), the United Arab Emirates (AE), and Qatar (QA). For countries that use postal codes, a non-blank postal code is required. Do not invent placeholder postal codes. Street address, city, and country code remain required when an address is supplied.

external_ref
string

An external reference used to match an existing involved party. For manufacturer type, this is a reference to the location of the manufacturer. For all other types, this is a reference to the company entity associated with the involved party.

name
string

The name of involved party.

type
required
string

The type of involved party.

Enum: "consignee" "importer_of_record" "seller" "buyer" "manufacturer"
mid_code
string

MID (Manufacturer ID) code. Only applicable for the US entries.

incoterm
string

Incoterm of the shipment to which this commercial invoice belongs.

Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP" "DPU"
is_related_parties
boolean

Whether there was a related parties transaction as defined by CBP. Only applicable for the US entries.

object or Array of objects

Set of custom key-values specific to the object. The keys are strings and values are arrays of strings. The set of valid keys is always the consignee's list of keys, even if call was made by a different party. Please contact Flexport representative before sending any attributes in this field.

One of:

Object format.

example_key
Array of strings
currency
string or null

Currency code for the commercial invoice. If omitted or null, derived from line_items[].value.currency_code. In that case, at least one line is required and every line must provide the same currency. Requests with mixed line currencies must supply a header currency. A supplied header currency is preserved.

invoice_date
string or null <date>

Represents the invoice date as an ISO-8601 date string (YYYY-MM-DD).

Array of objects (CreateCommercialInvoiceChargeAdjustment)

List of charge adjustments.

Array
amount
required
string <decimal>

Adjustment value. When applied_as is "percentage", this represents the percentage as a decimal between -1.0 and 1.0 (e.g., 0.15 for 15%, -0.05 for -5%).

currency_code
string

Adjustment currency. Must be provided in case of non-percentage adjustment.

code
required
string

Adjustment code.

Enum: "COMMISSIONS_AND_BROKERAGE" "SALVAGING_AND_PACKAGING_MEANS" "MATERIALS_COMPONENT_PARTS" "PRODUCTION_TOOLS_AND_MOLDS" "PRODUCTION_MATERIALS" "FOREIGN_INPUTS_AND_MATERIALS" "ROYALTIES_AND_LICENSING" "RESALE_TRANSFER_PROCEEDS" "TRANSPORT_HANDLING_INSURANCE" "INDIRECT_PAYMENTS" "ARTICLE_71_ADJUSTMENT" "POST_ENTRY_TRANSPORTATION" "POST_IMPORTATION_COSTS" "IMPORT_DUTIES_OR_OTHER_CHARGES" "INTEREST_EXPENSES" "REPRODUCTION_RIGHTS" "PURCHASING_COMMISSIONS" "DEDUCTIONS_DISCOUNTS_REBATES" "OTHER_ADDITIONS" "OTHER_DEDUCTIONS"
client_defined_code
string

Client specific adjustment code not included in the existing adjustment code enums.

applied_to
string
Default: "value"

The value to which the adjustment is applied

Enum: "VALUE" "VAT"
applied_as
required
string

Type of the adjustment applied

Enum: "PER_UNIT" "FLAT_RATE" "PERCENTAGE"
manifest_quantity
integer

The total manifest quantity (packaging) for the commercial invoice.

manifest_quantity_unit_type
string

The unit type for the manifest quantity. If nothing is specified, defaults to CARTON

Enum: "CARTON" "PACKAGE"
Responses
202
400

Bad Request

post/commercial_invoices
Request samples
application/json

Gross weight is allocated as 40 kg and 60 kg by line quantity. The supplied net weights remain 10 kg and 20 kg.

{
  • "invoice_number": "INV-MIXED-WEIGHTS-001",
  • "currency": "USD",
  • "total_gross_weight": {
    • "value": 100,
    • "unit": "kg"
    },
  • "line_items": [
    • {
      • "quantity": {
        },
      • "price_per_unit": {
        },
      • "value": {
        },
      • "net_weight": {
        },
      • "product": {
        }
      },
    • {
      • "quantity": {
        },
      • "price_per_unit": {
        },
      • "value": {
        },
      • "net_weight": {
        },
      • "product": {
        }
      }
    ]
}
Response samples
application/json

Accepted

{}

Retrieve a commercial invoice

Retrieves the details of a single commercial invoice.

Request
path Parameters
id
required
string

The unique id for the requested commercial invoice

Responses
200

Success

Response Schema: application/json
_object
string
self
string
version
integer
object (CommercialInvoice)
_object
string

Type of the object. Always /commercial_invoice for this object.

id
string

Unique identifier for the commercial invoice.

invoice_number
string

Invoice number on the commercial invoice, typically used for display purposes.

digitization_status
string or null

Status about if the digitization process for this commercial invoice is complete. If it is not complete, then the commercial invoice should be considered a draft that can change.

Enum: "pending" "reviewed" "complete"
Array of objects (CommercialInvoiceLineItem)

List of line items on the commercial invoice.

Array of objects (CustomsInvolvedParty)

List of parties involved in the commercial transaction.

incoterm
string

Incoterm of the shipment to which this commercial invoice belongs.

Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP" "DPU"
is_related_parties
boolean

Whether there was a related parties transaction as defined by CBP. Only applicable for the US entries.

Array of objects (Address)

List of manufacturer addresses for items on this invoice.

metadata
object (Metadata)

Set of custom key-values specific to the object. The keys are strings and values are arrays of strings. The set of valid keys is always the consignee's list of keys, even if call was made by a different party.

object (ShipmentRef)
total_unit_count
string

Total units on this commercial invoice.

object (Money)
object (Volume)
object (Weight)
order_number
string or null

Represents which order the invoice is linked to. This can be null.

currency
string

Currency code for the commercial invoice.

invoice_date
string or null <date>

Represents date of the invoice. This can be null.

updated_at
string or null <date-time>

Represents the last time the invoice was updated. This can be null.

Array of objects (CommercialInvoiceChargeAdjustment)

List of charge adjustments.

manifest_quantity
integer

The total manifest quantity (packaging) for the commercial invoice.

manifest_quantity_unit_type
string

The unit type for the manifest quantity. If nothing is specified, defaults to CARTON

Enum: "CARTON" "PACKAGE"
400

error

get/commercial_invoices/{id}
Response samples
application/json

Success

{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/commercial_invoices/abcxyz-23456-def",
  • "version": 3,
  • "data": [
    • {
      • "_object": "/commercial_invoice",
      • "id": "abc123-456-def",
      • "invoice_number": "INV-2024-8472",
      • "digitization_status": "complete",
      • "currency": "USD",
      • "invoice_date": "2024-03-15",
      • "order_number": "PO-2024-0042",
      • "incoterm": "FOB",
      • "is_related_parties": false,
      • "manifest_quantity": 250,
      • "manifest_quantity_unit_type": "CARTON",
      • "manufacturer_addresses": [
        ],
      • "total_value": {
        },
      • "total_unit_count": "750",
      • "total_weight": {
        },
      • "total_volume": {
        },
      • "charge_adjustments": [
        ],
      • "involved_parties": [
        ],
      • "line_items": [
        ],
      • "updated_at": "2024-03-15T14:22:18.500Z",
      • "shipment": {}
      }
    ]
}

Commercial Invoice is created or updatedWebhook

This webhook is sent when the asynchronous processing of a commercial invoice create/update operation completes.

When data.status is PROCESSING_STATUS_FAILED, the data.error field contains a human-readable description of what went wrong. The table below lists the errors you may encounter, their cause, and how to resolve them.

Error message Cause Suggested fix
Unable to locate shipment with provided identifier. The shipment identifier (id or ref) in the request does not match a shipment in your account. Verify the shipment identifier is correct and belongs to your account, then resubmit.
Provided shipment does not have one or more container(s) listed on the commercial invoice. A container number on a line item is not present on the referenced shipment. Ensure every line-item container number exists on the shipment before resubmitting.
One or more line items' currency do not match provided invoice level currency. A line item's currency code differs from the invoice-level currency. Make all line-item currencies match the invoice currency.
Provided currency code {currency_code} does not exist. The supplied currency code is not a recognized ISO currency. Use a valid ISO 4217 currency code.
customs_proration {value} cannot be set when charge adjustments are provided. customs_proration and charge_adjustments were both supplied, but they are mutually exclusive. Send either customs_proration or charge_adjustments, not both.
Document line number(s) invalid. One or more document_line_number values are invalid. Provide valid, in-range document line numbers for each line item.
All or none of the line items must provide document_line_number consistently. Some line items include document_line_number while others do not. Set document_line_number on all line items, or on none of them.
One or more involved parties on the commercial invoice are invalid. An entry in involved_parties is malformed or references an unknown party. Check each involved party's required fields and company_entity_ref.
Manufacturer (MID: {mid_code}) does not exist in your network. The manufacturer MID is not present in your network. Add the manufacturer to your network, or correct the MID code.
Product with SKU {sku} does not exist or has been archived. The referenced product SKU is missing or has been archived. Use an active product SKU, or enable product creation for the line item.
Product(s) were not found with the provided sku and products creation are disabled. The SKU was not found and automatic product creation is disabled. Create the product first, or enable product creation.
Line item with ID {line_item_id} does not exist. An update referenced a line-item ID that is not on this invoice. Use a valid line-item ID, or omit the ID to create a new line item.
One or more line items are allocated by Customs and cannot be changed. A line item is locked because it is allocated by a customs entry. Line items allocated by Customs cannot be modified.
Commercial Invoice is being used in a customs entry and cannot be updated. The invoice is locked by an active customs entry. The invoice cannot be updated while it is used in a customs entry.
Commercial Invoice already exists for the client and seller. A duplicate invoice for the same client and seller was detected. Update the existing invoice instead of creating a duplicate.
Failed to update metadata with provided data. Make sure each key exists in your schema. A metadata key is not defined in your configured schema. Ensure each metadata key exists in your schema before resubmitting.
Client not enrolled in shipmentless commercial invoices, Must provide shipment details. Shipment details were omitted, but your account requires a shipment. Include shipment details, or contact Flexport support to enable shipmentless commercial invoices.
An internal error occurred while processing the commercial invoice. A Flexport-side processing issue occurred (for example, while looking up or creating a company entity or location). Retry the request. If the problem persists, contact Flexport support with your request_id.
Request
Request Body schema: application/json
required

A notification about operation completion.

object
_object
string

Type of object, always /async_api/commercial_invoice here.

commercial_invoice_fid
string

An identifier of the created/updated commercial invoice in Flexport systems. Only present when processing is successful.

request_id
string

A unique request ID provided by the client in the original request.

status
string

Operation completion status.

Enum: "PROCESSING_STATUS_SUCCESSFUL" "PROCESSING_STATUS_FAILED"
commercial_invoice_number
string

Commercial invoice number supplied in the original request.

error
string

A human-readable description of an error. Only present when processing has failed.

_object
string

Type of the object, always /event here

id
integer

A unique ID of a webhook notification

version
integer
created_at
string
occurred_at
string
type
string

Webhook event type, containing information about the operation it refers to

Responses
200

Return a 200 response to indicate that webhook has been received successfully.

Request samples
application/json

Commercial invoice was successfully created or updated.

{
  • "_object": "/event",
  • "id": 987654,
  • "type": "/async_api/commercial_invoice#post",
  • "created_at": "2025-01-02T12:34:56.123Z",
  • "occurred_at": "2025-01-02T12:34:56.321Z",
  • "version": 3,
  • "data": {
    • "_object": "/async_api/commercial_invoice",
    • "request_id": "11210440-d15f-4699-bda2-46d3b8d3e044",
    • "status": "PROCESSING_STATUS_SUCCESSFUL",
    • "commercial_invoice_number": "ABCDEFGHIJKLMNOP",
    • "commercial_invoice_fid": "flx::core:commercial_invoice:dbid/12345"
    }
}
➔ Next to Customs Entries