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. 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)

List of line items on the commercial invoice.

Array
document_line_number
integer

Line number on the commercial invoice document.

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

Total quantity for this line item.

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).

object (VolumeCreate)
object

Weight excluding packaging.

object

Weight excluding packaging, tags, labels, instruction manuals, etc.

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.

required
Array of objects (CreateCustomsInvolvedParty)

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.

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
required
string

Currency code for the commercial invoice.

invoice_date
string or null <date>

Represents date of the invoice. This can be null.

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

Minimal example referencing existing products by SKU only and involved parties by company_entity_ref. Manufacturer is specified at invoice level.

{
  • "invoice_number": "INV-2024-001",
  • "currency": "USD",
  • "invoice_date": "2024-01-15",
  • "is_related_parties": false,
  • "manifest_quantity": 100,
  • "manifest_quantity_unit_type": "CARTON",
  • "charge_adjustments": [
    • {
      • "code": "transport_handling_insurance",
      • "amount": 150,
      • "currency_code": "USD",
      • "applied_as": "flat_rate",
      • "applied_to": "value"
      },
    • {
      • "code": "deductions_discounts_rebates",
      • "amount": 5,
      • "applied_as": "percentage",
      • "applied_to": "value"
      }
    ],
  • "involved_parties": [
    • {
      • "type": "seller",
      • "company_entity_ref": "my-seller-ref-1"
      },
    • {
      • "type": "buyer",
      • "company_entity_ref": "my-buyer-ref-1"
      },
    • {
      • "type": "manufacturer",
      • "company_entity_ref": "my-manufacturer-ref-1"
      }
    ],
  • "line_items": [
    • {
      • "document_line_number": 1,
      • "price_per_unit": {
        },
      • "value": {
        },
      • "quantity": {
        },
      • "purchase_order_number": "PO-9876-ABC",
      • "po_line_item_number": "1",
      • "weight": {
        },
      • "volume": {
        },
      • "product": {
        }
      },
    • {
      • "document_line_number": 2,
      • "price_per_unit": {
        },
      • "value": {
        },
      • "quantity": {
        },
      • "purchase_order_number": "PO-9876-ABC",
      • "po_line_item_number": "2",
      • "weight": {
        },
      • "volume": {
        },
      • "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