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": 2,
  • "data": {
    • "_object": "/api/collections/paginated",
    • "prev": "https://api.flexport.com/commercial_invoices?page=1&per=10",
    • "next": null,
    • "data": [
      • {
        }
      ]
    }
}

Create and return a new commercial invoice

The Commercial Invoices POST endpoint needs special permission to access. Please contact your Flexport Sales representative if you are interested in using this endpoint.

Request
Request Body schema: application/json
required
shipment_id
integer

Flexport's unique identifier for the shipment. Either shipment_id or shipment_ref is required.

shipment_ref
string

Your custom string used to refer to the shipment. Can be used to look up or reference the shipment later on. Either shipment_id or shipment_ref is 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 (CreateInvolvedParty)
Array
type
required
string
company_entity_ref
required
string

Your custom string used to refer to the company entity. Can be used to look up or reference the company entity later on.

currency_code
required
string

The currency being used on the commercial invoice.

is_related_parties
boolean

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

required
object (MoneyCreate)
amount
string <decimal>
currency_code
string
manufacturer_refs
Array of strings
Deprecated

[DEPRECATED] Array of your custom strings used to refer to a manufacturer location.

required
Array of objects (CreateCommercialInvoiceLineItem)
Array
document_line_number
integer

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

purchase_order_number
string
po_line_item_number
string
Default: ""

Purchase order line item number

container_number
string
country_of_origin
string
product_sku
required
string

The SKU of the product associated with this line item as it is stored in Flexport's system.

manufacturer_ref
string
Deprecated

[DEPRECATED] Your custom string used to refer to a manufacturer location.

required
object (CreateQuantity)
object (MoneyCreate)
object (MoneyCreate)
required
object (MoneyCreate)
required
object (MoneyCreate)
object (WeightCreate)
object (WeightCreate)
object (WeightCreate)
object (VolumeCreate)
object or Array of objects (MetadataCreate)
object or Array of objects (MetadataCreate)
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
200

The created commercial invoice

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)
Array of objects (CustomsInvolvedParty)
is_related_parties
boolean

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

Array of objects (Address)
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

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

currency
string
invoice_date
string

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.

400

error

post/commercial_invoices
Request samples
application/json
{
  • "shipment_id": 79683,
  • "shipment_ref": "PO-123",
  • "invoice_number": "INVOICE-04-05-2020",
  • "involved_parties": [
    • {
      • "type": "string",
      • "company_entity_ref": "string"
      }
    ],
  • "currency_code": "USD",
  • "is_related_parties": false,
  • "proration_amount": {
    • "amount": "12.34",
    • "currency_code": "USD"
    },
  • "manufacturer_refs": [
    • "string"
    ],
  • "line_items": [
    • {
      • "document_line_number": 4,
      • "purchase_order_number": "9876-ABC",
      • "po_line_item_number": 12,
      • "container_number": "522932-1",
      • "country_of_origin": "CN",
      • "product_sku": "PRODUCT-123",
      • "manufacturer_ref": "string",
      • "quantity": {
        },
      • "net_value": {
        },
      • "first_sale_value": {
        },
      • "value": {
        },
      • "price_per_unit": {
        },
      • "gross_weight": {
        },
      • "net_weight": {
        },
      • "net_net_weight": {
        },
      • "volume": {
        },
      • "metadata": "{color: [\"red\", \"blue\"], size: [\"large\", \"medium\", \"small\"]}"
      }
    ],
  • "metadata": "{color: [\"red\", \"blue\"], size: [\"large\", \"medium\", \"small\"]}"
}
Response samples
application/json

Success

{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/commercial_invoices",
  • "version": 2,
  • "data": {
    • "_object": "/commercial_invoice",
    • "id": "abcxyz-23456-def",
    • "invoice_number": "ABCDEFGHIJKLMNOP",
    • "digitization_status": "complete",
    • "manufacturer_addresses": [
      • {
        }
      ],
    • "total_value": {
      • "_object": "/money",
      • "amount": "100",
      • "currency_code": "USD"
      },
    • "total_unit_count": "12345",
    • "total_weight": {
      • "_object": "/quantity/weight",
      • "value": 100,
      • "unit": "kg"
      },
    • "total_volume": {
      • "_object": "/quantity/volume",
      • "value": 100,
      • "unit": "cbm"
      },
    • "line_items": [
      • {
        }
      ],
    • "shipment": {}
    }
}

Update an existing commercial invoice

The Commercial Invoices PATCH endpoint needs special permission to access. Please contact your Flexport Sales representative if you are interested in using this endpoint.

Request
Request Body schema: application/json
required
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.

currency_code
string

The currency being used on the commercial invoice.

is_related_parties
boolean

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

object (Money)
_object
string

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

amount
string <decimal>
currency_code
string
manufacturer_refs
Array of strings
Array of objects (CreateCommercialInvoiceLineItem)
Array
document_line_number
integer

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

purchase_order_number
string
po_line_item_number
string
Default: ""

Purchase order line item number

container_number
string
country_of_origin
string
product_sku
required
string

The SKU of the product associated with this line item as it is stored in Flexport's system.

manufacturer_ref
string
Deprecated

[DEPRECATED] Your custom string used to refer to a manufacturer location.

required
object (CreateQuantity)
object (MoneyCreate)
object (MoneyCreate)
required
object (MoneyCreate)
required
object (MoneyCreate)
object (WeightCreate)
object (WeightCreate)
object (WeightCreate)
object (VolumeCreate)
object or Array of objects (MetadataCreate)
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
200

The updated commercial invoice

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)
Array of objects (CustomsInvolvedParty)
is_related_parties
boolean

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

Array of objects (Address)
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

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

currency
string
invoice_date
string

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.

400

error

patch/commercial_invoices
Request samples
application/json
{
  • "invoice_number": "INVOICE-04-05-2020",
  • "currency_code": "USD",
  • "is_related_parties": false,
  • "proration_amount": {
    • "_object": "/money",
    • "amount": "12.34",
    • "currency_code": "USD"
    },
  • "manufacturer_refs": [
    • "string"
    ],
  • "line_items": [
    • {
      • "document_line_number": 4,
      • "purchase_order_number": "9876-ABC",
      • "po_line_item_number": 12,
      • "container_number": "522932-1",
      • "country_of_origin": "CN",
      • "product_sku": "PRODUCT-123",
      • "manufacturer_ref": "string",
      • "quantity": {
        },
      • "net_value": {
        },
      • "first_sale_value": {
        },
      • "value": {
        },
      • "price_per_unit": {
        },
      • "gross_weight": {
        },
      • "net_weight": {
        },
      • "net_net_weight": {
        },
      • "volume": {
        },
      • "metadata": "{color: [\"red\", \"blue\"], size: [\"large\", \"medium\", \"small\"]}"
      }
    ],
  • "metadata": {
    • "purchase_order": [
      • "12345"
      ],
    • "sku": [
      • "abc123"
      ]
    }
}
Response samples
application/json

Success

{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/commercial_invoices",
  • "version": 2,
  • "data": {
    • "_object": "/commercial_invoice",
    • "id": "abcxyz-23456-def",
    • "invoice_number": "ABCDEFGHIJKLMNOP",
    • "digitization_status": "complete",
    • "manufacturer_addresses": [
      • {
        }
      ],
    • "total_value": {
      • "_object": "/money",
      • "amount": "100",
      • "currency_code": "USD"
      },
    • "total_unit_count": "12345",
    • "total_weight": {
      • "_object": "/quantity/weight",
      • "value": 100,
      • "unit": "kg"
      },
    • "total_volume": {
      • "_object": "/quantity/volume",
      • "value": 100,
      • "unit": "cbm"
      },
    • "line_items": [
      • {
        }
      ],
    • "shipment": {}
    }
}

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)
Array of objects (CustomsInvolvedParty)
is_related_parties
boolean

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

Array of objects (Address)
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

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

currency
string
invoice_date
string

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.

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": 2,
  • "data": {
    • "_object": "/commercial_invoice",
    • "id": "abcxyz-23456-def",
    • "invoice_number": "ABCDEFGHIJKLMNOP",
    • "digitization_status": "complete",
    • "manufacturer_addresses": [
      • {
        }
      ],
    • "total_value": {
      • "_object": "/money",
      • "amount": "100",
      • "currency_code": "USD"
      },
    • "total_unit_count": "12345",
    • "total_weight": {
      • "_object": "/quantity/weight",
      • "value": 100,
      • "unit": "kg"
      },
    • "total_volume": {
      • "_object": "/quantity/volume",
      • "value": 100,
      • "unit": "cbm"
      },
    • "line_items": [
      • {
        }
      ],
    • "shipment": {}
    }
}
➔ Next to Customs Entries