Customs Order

Endpoints relating to Customs Order objects

Create or update a Customs Order

Create or update a Customs Order.

To determine if a new order will be created or an existing order will be updated, the following rules apply:

  1. If metadata.shipment_id is passed, the request is an update of this FLEX-ID.
  2. If metadata.customs_order_id is passed, the request is an update of this customs order.
  3. If metadata.source_document is passed and an order already exists for that id or external_ref, the request is an update for this document.
  4. Otherwise, matching to existing order is done by bill numbers:
    1. If only a master bill of lading (MBL), regular bill, master air waybill (MAWB) or truck bill of lading number is passed, this request is an update if an existing order with the exact same bill number exists, otherwise a new order is created.
    2. If house bill of lading or house air waybill numbers are passed, this order is an update if an existing order with at least the same bill number(s) exists, but it can have additional bill numbers. Otherwise a new order is created. Additionally, if a MBL or MAWB is also passed, the existing order must have either the same bill number, of it must be unknown. It can not be a different number.
Request
Request Body schema: application/json
required
name
required
string non-empty

Human-readable name for the order

incoterm
string (Incoterm)

The International Commercial Term variant used

If omitted when creating a truck request, this defaults to EXW.

If omitted when creating a non-truck request, this defaults to FOB.

If omitted when updating an existing order, the existing incoterm is preserved when valid for the requested freight mode.

Truck updates default to EXW if the existing incoterm is not DDP or EXW.

Truck requests only permit DDP or EXW.

Enum: "CFR" "CIF" "CIP" "CPT" "DAP" "DAT" "DDP" "DPU" "EXW" "FAS" "FCA" "FOB"
object (CustomsOrderServices)

The desired services for this order.

Not specifying or specifying null indicates:

  • For new orders: service not performed
  • For existing orders: no change

Note: services requested might not correspond directly to services invoiced. For example: product classification can be included in import filing service.

bco
boolean or null

Perform Beneficial Cargo Owner (BCO) management

commercial_invoice_digitization
boolean or null

Digitize commercial invoices (CI) documents. Implicitly enabled when import customs is enabled

export_customs
boolean or null

Perform filings required to export goods from Country of Origin.

delivery
boolean or null

Move goods by truck from port of unloading to destination address (drayage)

ftz_e214_filing
boolean or null
Default: false

Perform E214 filing required to move goods into a Foreign Trade Zone (FTZ) in the US.

ftz_entry
boolean or null

Perform filings required to import goods from a Foreign/Free Trade Zone (FTZ) into the country of import.

import_customs
boolean or null

Perform filings required to import goods into country of import.

insurance
boolean or null

Insure cargo

pickup
boolean or null
Default: false

Move goods by truck from origin address to port of loading.

pre_departure_authorization
boolean or null

Perform customs filings done by the importer, required prior to main leg vessel departure. For the US this included Importer Security Filing (ISF), but not Automated Manifest System (AMS) filing.

product_classification
boolean or null

Classify products from commercial invoices. Implicitly enabled when import customs is enabled

currency_code
string (CustomsOrderCurrencyCode) [A-Z]{3}
Default: "USD"

The base currency for the order quote and invoices. ISO 4217 currency code.

Not specifying or specifying null indicates:

  • For creation: USD
  • For updating: no change
required
Ocean FCL Freight Details (object) or Ocean LCL Freight Details (object) or Air Freight Details (object) or Truck FTL Freight Details (object) (CustomsOrderRequestFreightDetails)
One of:

Details of the main freight leg. Exact format is determined by the mode of transport, identified by the mode_of_transport field.

mode_of_transport
required
string
Enum: "OCEAN_FCL" "OCEAN_LCL" "AIR" "TRUCK_FTL"
Value: "OCEAN_FCL"
required
MBL (object) or HBL(s) (object) (OceanBillNumbers)

Ocean bill of lading numbers. At least one bill number is required, either a MBL or HBL.

object (OceanRoute)

Route of freight for ocean main freight leg

scac
string[A-Z]{4}

Standard Carrier Alpha Code

Array of objects (ContainerDetails)

Containers where the freight is in

object (CargoDetails)

Cargo Details

object (WeightUppercase)

Weight Object

object (VolumeUpperCase)

Volume Object

object (ShippingUnitDetails)

Shipping Unit Details

Array of Name (object) or External reference (object) or Address (object) (InvolvedPartyDetails)

All involved parties for the order

Array
Any of:

Involved Party Details. Either name, external_ref or address_details is required

name
required
string

Name of the party

type
required
string

Type of involved party

Enum: "BOOKING_PARTY" "BUYER" "CONSIGNEE" "CONSOLIDATOR" "DESTINATION_AGENT" "DESTINATION_WAREHOUSE" "EXPORT_CUSTOMS_AGENT" "FORWARDING_AGENT" "IMPORTER_OF_RECORD" "IMPORT_CUSTOMS_AGENT" "MANUFACTURER_SUPPLIER" "ORIGIN_AGENT" "ORIGIN_WAREHOUSE" "SCHEDULED_CONTAINER_STUFFING_LOCATION" "SELLER" "SHIPPER" "SHIP_TO_PARTY"
external_ref
string

Client-specific reference for the company entity

External reference (object) or Address (object) (AddressDetails)

Address Details. Either external_ref, or address_line1, city and country_code are required

object
object (CustomsDetails)

Details for customs services

countries_of_origin
Array of strings

The countries of manufacture, production, or growth. ISO 3166-1 alpha-2 country codes. This can be, but is not necessarily, only the country associated with the port of loading which indicates the exporting country.

country_of_import
string[A-Z]{2}

The country wherein the goods will ultimately be imported. ISO 3166-1 alpha-2 country code

Array of objects (Money)

Estimated total commercial invoice value of the goods for customs declaration. One entry per currency.

Array of objects (ShipmentTag)

Shipment tags for the order. Available shipment tags can be configured in Flexport App under 'Your Business' -> 'Settings' -> 'Shipment Preferences'

Array
attribute
required
string non-empty

Client-defined attribute

values
required
Array of strings non-empty

List of values for the attribute

purchase_order_numbers
Array of strings

List of purchase order numbers

required
object (CustomsOrderRequestMetadata)

Data for managing the order creation process, not directly related to the order itself.

is_update
boolean

If set, will ensure that the request is always treated as an update (true), or never treated as an update (false)

This might cause the request to return an error if the request is marked as not an update but there is an existing conflicting order, or if it is marked as an update but there is no existing order.

shipment_id
integer

FLEX-ID (FLEX-XXXXXXX) If passed in for an existing order, it will cause the request to act as an update for the existing order. If the specific id does not exists or is otherwise incorrect, it will either give an error or be ignored.

customs_order_fid
string

Flexport id for the customs order.

If passed in for an existing order, it will cause the request to act as an update for the existing order. If the specific id does not exists or is otherwise incorrect, an error will be returned.

request_id
string <uuid> (RequestMetadataRequestId)

Optional request ID for the request. Can also be passed as X-Request-ID header. If not given, one will be generated. This mainly is useful for correlating webhook responses to the original request.

webhook_id
string <uuid> (RequestMetadataWebhookId)

Optional Webhook-ID to be notified on when order creation has finished. Webhooks can be configured in Flexport App under 'Your Business' -> 'Settings' -> 'Webhooks'. Webhook will only be sent for a single request.

required
object (CustomsOrderSourceDocument)
Responses
202

Order request is pending

400

Bad request

post/customs_orders
Request samples
application/json
{
  • "name": "Import MBL SCAC57021412",
  • "incoterm": "FOB",
  • "services": {
    • "isf": true,
    • "import_customs": true
    },
  • "currency_code": "string",
  • "freight_details": {
    • "mode_of_transport": "OCEAN_FCL",
    • "bill_numbers": {
      • "master_bill_of_lading_number": "string",
      • "house_bill_of_lading_numbers": [
        ]
      },
    • "route": {
      • "vessel": {
        },
      • "voyage_tracking_number": "010E",
      • "origin_address": {
        },
      • "port_of_loading": {
        },
      • "transshipment_ports": [ ],
      • "port_of_unloading": {
        },
      • "inland_port": {
        },
      • "destination_address": {
        }
      },
    • "scac": "string",
    • "containers": [
      • {
        }
      ]
    },
  • "cargo_details": {
    • "weight": {
      • "value": 8305,
      • "unit": "KG"
      },
    • "volume": {
      • "value": 305,
      • "unit": "CBM"
      },
    • "shipping_unit_details": {
      • "count": 5,
      • "atomic_count": 5,
      • "shipping_unit_type": "CARTON"
      }
    },
  • "involved_parties": [
    • {
      • "type": "IMPORTER_OF_RECORD",
      • "name": "FLEXPORT INTERNATIONAL LLC",
      • "external_ref": "IMPORTER708"
      },
    • {
      • "type": "CONSIGNEE",
      • "name": "FLEXPORT INTERNATIONAL LLC",
      • "external_ref": "CONSIGNEE123"
      },
    • {
      • "type": "BUYER",
      • "name": "FLEXPORT INTERNATIONAL LLC",
      • "external_ref": "BUYER900"
      }
    ],
  • "customs_details": {
    • "country_of_origin": "CN",
    • "country_of_import": "US",
    • "estimated_total_commercial_invoice_value": [
      • {
        }
      ]
    },
  • "shipment_tags": [
    • {
      • "attribute": "ACME Inc. Order ID",
      • "values": [
        ]
      }
    ],
  • "purchase_order_numbers": [
    • "PO88087"
    ],
  • "request_metadata": {
    • "is_update": true,
    • "shipment_id": 3000000,
    • "customs_order_fid": "flx::customs:pre-order:a65f2d6e-3b1b-44fd-86b5-a9b7d83a7327",
    • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
    • "webhook_id": "a47606a1-5b39-4a81-9480-c2cb738ff675",
    • "source_document": {
      • "type": "OCEAN_BILL_OF_LADING",
      • "fid": "flx::customs:inbound-isf:a65f2d6e-3b1b-44fd-86b5-a9b7d83a7327",
      • "externalRef": "ISF Worksheet MBL SCAC123456789"
      }
    }
}
Response samples
application/json
{
  • "_object": "/api/response",
  • "version": 2,
  • "self": "https://api.flexport.com/customs_orders",
  • "data": {
    • "fid": "flx::customs:pre-order:a65f2d6e-3b1b-44fd-86b5-a9b7d83a7327",
    • "status": "REQUESTED",
    • "shipment_id": 3000000,
    • "name": "Import MBL SCAC57021412",
    • "services": {
      • "isf": true,
      • "import_customs": true
      },
    • "freight_details": {
      • "mode_of_transport": "OCEAN_FCL",
      • "bill_numbers": {
        },
      • "customer_supplied_bill_numbers": {
        }
      },
    • "source_documents": [
      • {
        }
      ],
    • "problems": [
      • {
        },
      • {
        }
      ],
    • "created_at": "2019-08-24T14:15:22Z",
    • "updated_at": "2019-08-24T14:15:22Z"
    }
}

Retrieve a customs order by fid

Retrieve the latest status of the customs order, which might be merged from multiple requests.

Request
path Parameters
customs_order_fid
required
string

Customs order fid.

Note that : must be URL-encoded as %3A following normal URL encoding rules

Example: flx::customs:pre-order:a65f2d6e-3b1b-44fd-86b5-a9b7d83a7327
Responses
200

The customs order

Response Schema: application/json
_object
required
string
Value: "/api/response"
version
required
integer
Value: 2
self
required
string
required
object (CustomsOrder)

A customs order

fid
required
string

Flexport id for the customs order

status
required
string (CustomsOrderStatus)

Status of the order

  • REQUESTED indicates that the order is still being created
  • CREATED indicates that this order is active and has a FLEX-ID assigned
  • CANCELLED indicates this order has been cancelled
Enum: "REQUESTED" "CREATED" "CANCELLED"
shipment_id
integer or null

FLEX-ID (FLEX-XXXXXXX), a.k.a. shipment id Available unless status is REQUESTED

name
required
string

Human-readable name for the order

required
object (CustomsOrderServices)

The services that fill be fulfilled for this order

required
object
Array of objects (CustomsOrderSourceDocument)
Array of objects or null (CustomsOrderProblem)
created_at
required
string <date-time>
updated_at
required
string <date-time>
400

Bad request, e.g. malformed FID

404

Customs order not found

get/customs_orders/{customs_order_fid}
Response samples
application/json
{
  • "_object": "/api/response",
  • "version": 2,
  • "self": "https://api.flexport.com/customs_orders/flx::customs:pre-order:a65f2d6e-3b1b-44fd-86b5-a9b7d83a7327",
  • "data": {
    • "fid": "flx::customs:pre-order:a65f2d6e-3b1b-44fd-86b5-a9b7d83a7327",
    • "status": "REQUESTED",
    • "shipment_id": 3000000,
    • "name": "Import MBL SCAC57021412",
    • "services": {
      • "isf": true,
      • "import_customs": true
      },
    • "freight_details": {
      • "mode_of_transport": "OCEAN_FCL",
      • "bill_numbers": {
        },
      • "customer_supplied_bill_numbers": {
        }
      },
    • "source_documents": [
      • {
        }
      ],
    • "problems": [
      • {
        },
      • {
        }
      ],
    • "created_at": "2019-08-24T14:15:22Z",
    • "updated_at": "2019-08-24T14:15:22Z"
    }
}
➔ Next to Invoices