Commercial Invoices

Endpoints relating to Commercial Invoice objects

Create a commercial invoice

Create a new commercial invoice.

Request
Request Body schema: application/json
required
invoice_number
required
string

Invoice number on the commercial invoice, typically used for display purposes. Uniqueness is based on the supplier Involved Party. There can be multiple commercial invoices with the same invoice_number only if they have different suppliers.

required
Array of objects (InvolvedParty)

List of involved parties. Note that manufacturer at the invoice level will apply to all line items within the CI.

Array
type
required
string

The type of involved party. Must be manufacturer at line item level

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

The name of involved party.

address_line1
string

If external_ref is not provided, address_line_1 is required.

address_line2
string
address_line3
string
address_line4
string
address_line5
string
address_line6
string
city
string

If external_ref is not provided, city is required.

state_province
string

If external_ref is not provided, state_province is required.

postal_code
string

If external_ref is not provided, postal_code is required.

country_code
string

Two-character country code. If external_ref is not provided, country_code is required.

external_ref
string

If address is not provided, external_ref is required.

mid_code
string

Correctly formatted MID (Manufacturer ID) Code.

is_related_parties
required
boolean

Whether there was a related parties transaction as defined by CBP.

currency_code
required
string

The currency being used on the commercial invoice.

terms_of_sale
string
required
Array of objects (LineItem)

List of line items. Note that only full replacement of the list is allowed.

Array
mid_code
string

Manufacturer ID code.

object (InvolvedParty)

Involved party

country_of_origin
string
required
object (Quantity)

Quantity Object

object (Money)

Money Object

required
object (Money)

Money Object

required
object (Money)

Money Object

object (Money)

Money Object

object (Money)

Money Object

object (Weight-2)

Weight Object

object (Weight-2)

Weight excluding packaging.

object (Weight-2)

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

object (Volume-2)

Volume Object

container_number
string
document_line_number
integer

Document line number that this data represents. Counting from 1.

purchase_order_number
string
po_line_item_number
string

Purchase order line item number.

required
object (Product)

Product

object or Array of objects (MetadataCreate-2)
shipment_ref
string

External reference to a Flexport shipment. Only optional if client is enrolled in the shipmentless commercial invoice feature.

shipment_id
integer

Flexport's unique identifier for shipment. Only optional if client is enrolled in the shipmentless commercial invoice feature.

invoice_date
string

date of invoice, in the format of yyyy-MM-dd.

required
object (Money)

Money Object

amount
required
double
currency_code
string
object or Array of objects (MetadataCreate-2)
One of:

Metadata has two allowed formats. Either array format or object format. Refer to the metadata section in this documentation for more information.

example_key
Array of strings
Responses
202

Accepted

400

Bad Request

401

Bad token

500

Unknown error

post/commercial_invoices
Request samples
application/json
{
  • "invoice_number": "ABCD1234",
  • "involved_parties": [
    • {
      • "type": "consignee",
      • "name": "party_name",
      • "address_line1": "760 Market Street",
      • "address_line2": "Floor 8",
      • "address_line3": null,
      • "address_line4": null,
      • "address_line5": null,
      • "address_line6": null,
      • "city": "San Francisco",
      • "state_province": "CA",
      • "postal_code": "94102",
      • "country_code": "US",
      • "external_ref": "ref_1234"
      }
    ],
  • "mid_code": "mid_code",
  • "is_related_parties": true,
  • "currency_code": "USD",
  • "terms_of_sale": "terms_of_sale",
  • "line_items": [
    • {
      • "mid_code": "mid_code",
      • "manufacturer_address": {
        },
      • "country_of_origin": "CN",
      • "quantity": {
        },
      • "net_value": {
        },
      • "value": {
        },
      • "unit_price": {
        },
      • "first_sale_value": {
        },
      • "final_sale_value": {
        },
      • "gross_weight": {
        },
      • "net_weight": {
        },
      • "net_net_weight": {
        },
      • "volume": {
        },
      • "container_number": "ABCD1234",
      • "document_line_number": 1234,
      • "purchase_order_number": "123456",
      • "po_line_item_number": "123456",
      • "product": {
        },
      • "metadata": "{color: [\"red\", \"blue\"], size: [\"large\", \"medium\", \"small\"]}"
      }
    ],
  • "shipment_ref": "shipment_ref",
  • "shipment_id": 123456,
  • "invoice_date": "2000-04-30",
  • "proration_amount": {
    • "amount": 1.23,
    • "currency_code": "USD"
    },
  • "metadata": "{color: [\"red\", \"blue\"], size: [\"large\", \"medium\", \"small\"]}"
}
Response samples
application/json

Accepted

{}

Update a commercial invoice

Update an existing commercial invoice

Request
Request Body schema: application/json
required
invoice_number
required
string

Invoice number on the commercial invoice, typically used for display purposes. Uniqueness is based on the supplier Involved Party. There can be multiple commercial invoices with the same invoice_number only if they have different suppliers.

Array of objects (InvolvedParty)

List of involved parties. Note that manufacturer at the invoice level will apply to all line items within the CI. Also, note that only full replacement of the list is allowed, meaning any value (including an empty array) will override the existing involved parties for this invoice. Omit this field completely from your request if you do not want to update the involved parties.

Array
type
required
string

The type of involved party. Must be manufacturer at line item level

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

The name of involved party.

address_line1
string

If external_ref is not provided, address_line_1 is required.

address_line2
string
address_line3
string
address_line4
string
address_line5
string
address_line6
string
city
string

If external_ref is not provided, city is required.

state_province
string

If external_ref is not provided, state_province is required.

postal_code
string

If external_ref is not provided, postal_code is required.

country_code
string

Two-character country code. If external_ref is not provided, country_code is required.

external_ref
string

If address is not provided, external_ref is required.

mid_code
string

Correctly formatted MID (Manufacturer ID) Code

is_related_parties
boolean

Whether there was a related parties transaction as defined by CBP.

currency_code
string

The currency being used on the commercial invoice.

terms_of_sale
string
Array of objects (LineItem)

List of line items. Note that only full replacement of the list is allowed, meaning any value (including an empty array) will override the existing line items for this invoice. Omit this field completely from your request if you do not want to update the line items.

Array
mid_code
string

Manufacturer ID code.

object (InvolvedParty)

Involved party

country_of_origin
string
required
object (Quantity)

Quantity Object

object (Money)

Money Object

required
object (Money)

Money Object

required
object (Money)

Money Object

object (Money)

Money Object

object (Money)

Money Object

object (Weight-2)

Weight Object

object (Weight-2)

Weight excluding packaging.

object (Weight-2)

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

object (Volume-2)

Volume Object

container_number
string
document_line_number
integer

Document line number that this data represents. Counting from 1.

purchase_order_number
string
po_line_item_number
string

Purchase order line item number.

required
object (Product)

Product

object or Array of objects (MetadataCreate-2)
invoice_date
string

date of invoice, in the format of yyyy-MM-dd.

object (Money)

Money Object

amount
required
double
currency_code
string
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.

Responses
202

Accepted

400

Bad Request

401

Bad token

404

Not Found

500

Unknown error

patch/commercial_invoices
Request samples
application/json
{
  • "invoice_number": "ABCD1234",
  • "involved_parties": [
    • {
      • "type": "consignee",
      • "name": "party_name",
      • "address_line1": "760 Market Street",
      • "address_line2": "Floor 8",
      • "address_line3": null,
      • "address_line4": null,
      • "address_line5": null,
      • "address_line6": null,
      • "city": "San Francisco",
      • "state_province": "CA",
      • "postal_code": "94102",
      • "country_code": "US",
      • "external_ref": "ref_1234"
      }
    ],
  • "mid_code": "mid_code",
  • "is_related_parties": true,
  • "currency_code": "USD",
  • "terms_of_sale": "terms_of_sale",
  • "line_items": [
    • {
      • "mid_code": "mid_code",
      • "manufacturer_address": {
        },
      • "country_of_origin": "CN",
      • "quantity": {
        },
      • "net_value": {
        },
      • "value": {
        },
      • "unit_price": {
        },
      • "first_sale_value": {
        },
      • "final_sale_value": {
        },
      • "gross_weight": {
        },
      • "net_weight": {
        },
      • "net_net_weight": {
        },
      • "volume": {
        },
      • "container_number": "ABCD1234",
      • "document_line_number": 1234,
      • "purchase_order_number": "123456",
      • "po_line_item_number": "123456",
      • "product": {
        },
      • "metadata": "{color: [\"red\", \"blue\"], size: [\"large\", \"medium\", \"small\"]}"
      }
    ],
  • "invoice_date": "2000-04-30",
  • "proration_amount": {
    • "amount": 1.23,
    • "currency_code": "USD"
    },
  • "metadata": "{color: [\"red\", \"blue\"], size: [\"large\", \"medium\", \"small\"]}"
}
Response samples
application/json

Accepted

{}

Retrieve a commercial invoice

Retrieve an existing commercial invoice by invoice number

Request
path Parameters
invoice_number
required
string

The unique number for the commercial invoice to be retrieved

Responses
200

Success

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

The commercial invoice data

invoice_number
string

Invoice number on the commercial invoice, typically used for display purposes. Uniqueness is based on the supplier Involved Party. There can be multiple commercial invoices with the same invoice_number only if they have different suppliers.

Array of objects (InvolvedParty)

List of involved parties. Note that manufacturer at the invoice level will apply to all line items within the CI.

mid_code
string

Correctly formatted MID (Manufacturer ID) codes.

is_related_parties
boolean

Whether there was a related parties transaction as defined by CBP.

currency_code
string

The currency being used on the commercial invoice.

terms_of_sale
string
Array of objects (LineItem)

List of line items. Note that only full replacement of the list is allowed.

shipment_ref
string

External reference to a Flexport shipment. Only optional if client is enrolled in the shipmentless commercial invoice feature.

shipment_id
integer

Flexport's unique identifier for shipment. Only optional if client is enrolled in the shipmentless commercial invoice feature.

invoice_date
string

date of invoice, in the format of yyyy-MM-dd.

object (Money)

Money Object

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.

error
object
400

Bad Request

401

Bad token

404

Not Found

500

Unknown error

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

Success

{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/commercial_invoices/ABCD1234",
  • "version": "2023-05-18",
  • "data": {
    • "invoice_number": "ABCD1234",
    • "involved_parties": [
      • {
        }
      ],
    • "mid_code": "mid_code",
    • "is_related_parties": true,
    • "currency_code": "USD",
    • "terms_of_sale": "terms_of_sale",
    • "line_items": [
      • {
        }
      ],
    • "shipment_ref": "shipment_ref",
    • "shipment_id": 123456,
    • "invoice_date": "2000-04-30",
    • "proration_amount": {
      • "amount": 1.23,
      • "currency_code": "USD"
      },
    • "metadata": "{color: [\"red\", \"blue\"], size: [\"large\", \"medium\", \"small\"]}"
    },
  • "error": null
}
➔ Next to Customs Entries