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.

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. Either this or company_entity_ref must be specified.

company_entity_ref
string

Reference to the company entity associated with this involved party. Either this or address must be specified.

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.

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