NAV

Introduction

Welcome to the Flexport API!

You can use our API to request quotes for shipments as well as retrieve information about specific shipments. The API is currently under heavy development and should be considered likely to change.

Making Requests

All API urls have the common prefix:

https://api.flexport.com/

We recommend always setting the Accept header to the version you wish to target; you should also set the Content-Type header to application/json if your request contains a payload

curl 'api_endpoint_here'
  -H 'Accept: application/vnd.flexport.v1'
  -H 'Content-Type: application/json'

Our API is accessible over HTTPS, is mostly RESTful, and speaks JSON in both directions.

The current API version is v1. The version you wish to target can be specified using an Accept header with the value application/vnd.flexport.v1. If you do not specify a version then your request will go to whatever is considered the current version. We suggest you always specify the version to ensure your application does not suddenly break.

As the API uses JSON for both requests and responses, we will assume that requests with a payload are using properly formatted JSON, however we still recommend setting the Content-Type header to the value application/json.

We describe endpoints throughout the documentation which are meant to be understood as living under the API subdomain, i.e. the endpoint /quotes corresponds to https://api.flexport.com/quotes.

Authentication

A generic authenticated request appears below:

curl 'api_endpoint_here'
  -H 'Accept: application/vnd.flexport.v1'
  -H 'Authorization: Token token="41a08de1c61033008bb1998ae0c66ed3"'

If your API key is not valid for any reason, you will receive the following response:

HTTP/1.1 401 Bad Request
Content-Type: application/json; charset=utf-8

{
  "errors":
  [
    {
      "code": "bad_token",
      "message": "Bad Token"
    }
  ]
}

We use API keys to allow access to the API. You can generate an api key as an Admin or a Billing user at https://flexport.com/account_settings/api.

We expect the key to be included with all API requests in a header that looks like the following:

Authorization: Token token="41a08de1c61033008bb1998ae0c66ed3"

Requests with bad tokens, either invalid or expired, will receive a response with a 401 status code and the error code bad_token in the format described here.

Shipments

Get shipment status

curl -v -X GET 'https://api.flexport.com/shipments'
  -H 'Accept:  application/vnd.flexport.v1'
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8


{"records":  [
  {
    "id": 12345,
    "flex_id":  "FLEX-12345",
    "name": "Test Shipment #1",
    "transportation_mode": "air",
    "container_type": "high_cubed",
    "freight_type": "port_to_door",
    "master_bill_number": "12345",
    "house_bill_number": "HAWP12345",
    "metric_units": true,
    "chargeable_weight": 123.4,
    "chargeable_volume": 444.3,
    "calculated_weight": 321.1,
    "calculated_volume": 233.2,
    "total_weight": 321.1,
    "total_volume": 233.2,
    "cargo_ready_date": "2015-07-22",
    "origin_pickup_date": "2015-07-22",
    "departure_date": "2015-07-23",
    "arrival_date": "2015-07-25",
    "delivery_date": "2015-07-28",
    "pieces": 5,
    "status": "Seller's Location",
    "freight_cost": 512.14,
    "customs_cost": 1402.43,
    "origin_address": "123 Shenzhenwan Highway Bridge, Shenzhen, Guangdong, CN",
    "destination_address": "Greenwood, IN, United States",
    "containers": [
      {
        "container_number": "ABCDEFGHIJK",
        "container_size": "fourty_five_ft_hc"
      }
    ],
    "commercial_invoices": [
      {
        "id": 54321,
        "invoice_number": "INV123",
        "currency_code": "USD",
        "manufacturer_address": {
          "street_address": "251 Red Lantern St",
          "street_address2": null,
          "city": "Laguna Niguel",
          "state": "CA",
          "zip": "92677",
          "country_code": "US",
          "name": "West Coast Factory",
          "external_ref": "company_b"
        },
        "commercial_invoice_line_items": [
          {
            "id": 123,
            "price_per_unit": "0.20",
            "total_price": "7600.0",
            "total_units": "40000.0",
            "purchase_order": "28CA",
            "document_line_number": 0,
            "total_weight": "0.0",
            "total_volume": "0.0",
            "product": {
              "id": 538672,
              "sku": "12345"
            }
          }
        ]
      }
    ],
    "departure_port":  {
      "id": 4934,
      "name": "Hong Kong International Airport, Chek Lap Kok, Hong Kong",
      "iata_code": "HKG",
      "country_code": "HK"
    },
    "arrival_port":  {
      "id": 210,
      "name": "Cincinnati/Northern Kentucky International Airport, Hebron, Kentucky (near Cincinnati), United States",
      "iata_code": "CVG",
      "country_code": "US"
    }
  }]
}

You can get the status of all of your shipments by querying this endpoint. This endpoint returns a response which contains a list of records.

Result

Success

In the event of successful request you will receive a response with a status code of 200 with a JSON body that contains the following values. All fields with the exception of id, flex_id, and name could be null.

Key Type Description
id Number A unique identifier for your shipment
flex_id String A human readable unique identifier for your shipment
name String The name of your shipment
transportation_mode Transportation Mode The transportation mode of your shipment
container_type Container Type The container-type of your shipment
freight_type Freight Type The freight type of your shipment
master_bill_number String The Master Bill Identifier for your shipment
house_bill_number String The House Bill Identifier for your shipment
metric_units Boolean Flag that tells you if weight and volume are being reported in Imperial or Metric
chargeable_weight Number (kg/lbs) The chargeable weight for your shipment (based on transportation type and weight and volume measurements)
chargeable_volume Number (cubic ft / cubic meters) The chargeable volume for your shipment (based on transportation type and weight and volume measurements)
total_weight Number (kg/lbs) The total weight of the shipment. If this is missing then this value will be computed from the individual products.
total_volume Number (cubic ft / cubic meters) The total volume of the shipment. If this is missing then this value will be computed from the individual products.
calculated_weight Number (kg/lbs) The weight of your shipment, calculated from individual products
calculated_volume Number (cubic ft / cubic meters) The volume of your shipment, calculated from individual products
cargo_ready_date String The date the Cargo was ready for pickup
origin_pickup_date String The date the cargo was picked up at origin
departure_date String The date the cargo left the departure port
arrival_date String The date the cargo arrived at the arrival port
delivery_date String The date the cargo was tendered to its final destination
pieces Number The number of items in the shipment
status Status The status of the shipment
freight_cost Number The dollar amount spent on freight
customs_cost Number The dollar amount spent on customs and duty
origin_address Address An Address object which represents where the shipment came from. Only valid on door-to-x shipments
destination_address Address An Address object which represents where the shipment will be delivered to. Only valid on x-to-door shipments
containers Container A list of container objects contained in the shipment
commercial_invoices Commercial Invoice A list of commercial invoices, their line items, and their products
departure_port Port A Port object.
arrival_port Port A Port object.

Create


# CREATE /shipments
curl -v -X POST 'https://api.flexport.com/shipments'
  -H 'Accept:  application/vnd.flexport.v1'
  -H 'Content-Type: application/json'
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'
  -d '{"record": {
    "name": "Shipment",
    "container_type": "high_cubed",
    "freight_type": "port_to_door",
    "transportation_mode": "air",
    "total_weight": "444",
    "total_volume": "444",
    "metric_units": true,
    "contains_li_ion": true,
    "contains_hazmat": true,
    "contains_magnets": false,
    "cargo_ready_date": "2016-03-16",
    "client_note": "ff",
    "target_delivery_date": "2016-04-16",
    "uses_customs_service": true,
    "wants_flexport_insurance": true,
    "origin_id": 1,
    "destination_id": 2
  }}'

A successful response to such a request results in a shipment record as described above in the list shipments section:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8

{
  "record": {
    "id": 12345,
    "flex_id": "FLEX-12345",
    "name": "Shipment",
    "transportation_mode": "air",
    "container_type": "high_cubed",
    "freight_type": "port_to_door",
    "master_bill_number": null,
    "house_bill_number": "",
    "metric_units": true,
    "chargeable_weight": "74000.0",
    "chargeable_volume": "444.0",
    "calculated_weight": "444.0",
    "calculated_volume": "444.0",
    "total_weight": "444.0",
    "total_volume": "444.0",
    "cargo_ready_date": "2016-03-16",
    "origin_pickup_date": null,
    "departure_date": null,
    "arrival_date": null,
    "delivery_date": null,
    "pieces": null,
    "status": "Seller's Location",
    "pickup_date": null,
    "freight_cost": 0,
    "customs_cost": 0,
    "origin_address": "Origin Location Name",
    "destination_address": "Destination Location Name"
  }
}

You can create a new shipment with a POST request. Upon success, the request will respond with a 200 and the newly created product.

A request should have a json body that contains a single record as described below

Parameters

Key Type Description
name String A human readable idenfier for your shipment
origin_id PlaceId The id of the Port or Network location your shipment originates from
destination_id PlaceId The id of the Port or Network location your shipment is going to
container_type Container Type A string representing the type of container your shipment is in
freight_type String A human readable unique identifier for your shipment
transportation_mode Transportation Mode The transportation mode of your shipment
metric_units Boolean Chooses between metric units or imperial units for total_weight and total_volume
total_weight Number The total weight of your shipment in kg (or lbs).
total_volume Number The total volume of your shipment in cubic meters (or cubic feet).
cargo_ready_date Date When the cargo will be ready for pickup. Formatted as Y-M-D (e.g. 2016-03-01)
target_delivery_date Date When you’d like the cargo to be delivered. Formatted as Y-M-D (e.g. 2016-03-01)
contains_li_ion Boolean True only if your shipment contains lithium ion
contains_hazmat Boolean True only if your shipment contains hazmat
contains_magnets Boolean True only if your shipment contains magnets
uses_customs_service Boolean True if you want customs clearance
wants_flexport_insurance Boolean True if you want us to insure your shipment
client_note String A freeform text field to tell us anything else about your shipment

Container Type

A container type is one of the following options

Transpotation Mode

Transporation Mode is one of the following options

A shipment response that fails due to an archived place

HTTP/1.1 422 Unprocessable Entity
Content-Type:  application/json; charset=utf-8

{
  "errors": {
    "destination_id": [
      {
        "error": "address is archived",
        "updated_address": {
          "id": 12345,
          "type": "Address",
          "location": "Supplier ABC, Brussels"
        }
      }
    ]
  }
}

PlaceId

A Place Id is a unique identifier for either a Port or a Network Address. Places are immutable. Once they are created they will never change.

If details of an address get edited, the old location will be archived and a new one will be created.

If that happens, we will return a 422 error as demonstrated on the right for an archived destination_id. If the address looks right, you can use the new Id to submit the same request.

Purchase Orders

List


curl -v -X GET 'https://api.flexport.com/purchase_orders' \
  -H 'Accept:  application/vnd.flexport.v1' \
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8

{"records": [
  {
    "id": 123,
    "name": "PO 1",
    "role": "buyer",
    "other_party_ref": "seller_1",
    "currency_code": "USD",
    "must_arrive_date": "2017-04-20",
    "cargo_ready_date": "2017-03-20",
    "transportation_mode": "ocean",
    "incoterm": "FOB",
    "memo": "Memo",
    "origin_port_ref": "origin_port_1",
    "destination_port_ref": "destination_port_1",
    "origin_location_ref": "origin_location_1",
    "destination_location_ref": "destination_location_1",
    "archived": false,
    "po_line_items": [
      {
        "id": 10,
        "line_item_number": 1,
        "product_sku": "ABCD123",
        "cargo_ready_date": "2017-03-20",
        "units": 50,
        "unit_cost": "10.5",
        "booking_line_items": [
          {
            "units": 10,
            "shipment_id": 1234
          }
        ]
      },
      {
        "id": 11,
        "line_item_number": 2,
        "product_sku": "ABCD124",
        "cargo_ready_date": "2017-03-20",
        "units": 170,
        "unit_cost": "40.5",
        "booking_line_items": [
        ]
      }
    ]
  }]
}

You can get a list of all of your purchase orders by querying this endpoint. This endpoint returns a response which contains a list of records.

Purchase Order

In the event of successful request you will receive a response with a status code of 200 with a JSON body that contains the following entries.

Key Type Description
id Number A unique identifier for this purchase order
name String Your unique identifier for this purchase order
role String Your role in this purchase order (buyer or seller)
other_party_ref String Your reference string for the other party
currency_code String The currency code being used in this purchase order
must_arrive_date String The must arrive date for this purchase order
cargo_ready_date String The cargo ready date for this purchase order
transportation_mode Transportation Mode The transportation mode used for this purchase order
incoterm String The incoterm used for this purchase order
memo String Your notes or instructions on this purchase order
origin_port_ref String Your reference string for the origin port
destination_port_ref String Your reference string for the destination port
origin_location_ref String Your reference string for the origin location
destination_location_ref String Your reference string for the destination location
archived Boolean Whether the purchase order is archived
po_line_items Array<Purchase Order Line Item> A list of the line items in this purchase order

Purchase Order Line Item

A PurchaseOrderLineItem is a JSON object with the following entries:

Key Type Description
id Number A unique identifier for this line item
line_item_number String Your unique identifier for this purchase order line item
product_sku String or Number SKU used to identify the product uniquely
cargo_ready_date String The cargo ready date for this line item
units Number The number of units for this line item
unit_cost String The cost per unit for this line item
booking_line_items Array<Booking Line Item> A list of the booked units and shipments associated with this line item

Booking Line Item

A BookingLineItem is a JSON object with the following entries:

Key Type Description
units Number The number of units for this line item
shipment_id Number The shipment id associated with this booking

Transportation Mode

The transportation mode for a Purchase Order can be one of the following strings:

Get

You can retrieve the record for one purchase order by passing the ID for the desired order to list endpoint.

Making a GET request to https://api.flexport.com/purchase_orders/:id, where :id is the ID of a pre-existing purchase order will return a 200 and JSON with a single record.


curl -v -X GET 'https://api.flexport.com/purchase_orders/123' \
  -H 'Accept:  application/vnd.flexport.v1' \
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8

{"record":
  {
    "id": 123,
    "name": "PO 1",
    "role": "buyer",
    "other_party_ref": "seller_1",
    "currency_code": "USD",
    "must_arrive_date": "2017-04-20",
    "cargo_ready_date": "2017-03-20",
    "transportation_mode": "ocean",
    "incoterm": "FOB",
    "memo": "Memo",
    "origin_port_ref": "origin_port_1",
    "destination_port_ref": "destination_port_1",
    "origin_location_ref": "origin_location_1",
    "destination_location_ref": "destination_location_1",
    "archived": false,
    "po_line_items": [
      {
        "id": 10,
        "line_item_number": 1,
        "product_sku": "ABCD123",
        "cargo_ready_date": "2017-03-20",
        "units": 50,
        "unit_cost": "10.5",
        "booking_line_items": [
          {
            "units": 10,
            "shipment_id": 1234
          },
        ]
      },
      {
        "id": 11,
        "line_item_number": 2,
        "product_sku": "ABCD124",
        "cargo_ready_date": "2017-03-20",
        "units": 170,
        "unit_cost": "40.5",
        "booking_line_items": [
        ]
      }
    ]
  }
}

You can get a list of all of your purchase_orders by querying this endpoint. This endpoint returns a response which contains a list of records.

Result

In the event of successful request you will receive a response with a status code of 200 with a JSON body that contains the following entries.

Key Type Description
id Number A unique identifier for this purchase_order
name String Your unique identifier for this purchase_order
role String Your role in this purchase order (buyer or seller)
other_party_ref String Your reference string for the other party
currency_code String The currency code being used in this purchase order
must_arrive_date String The must arrive date for this purchase order
cargo_ready_date String The cargo ready date for this purchase order
transportation_mode Transportation Mode The transportation mode used for this purchase order
incoterm String The incoterm used for this purchase order
memo String Your notes or instructions on this purchase order
origin_port_ref String Your reference string for the origin port
destination_port_ref String Your reference string for the destination port
origin_location_ref String Your reference string for the origin location
destination_location_ref String Your reference string for the destination location
archived Boolean Whether the purchase order is archived
po_line_items Array<Purchase Order Line Item> A list of the line items in this purchase order

Purchase Order Line Item

A Purchase Order Line Item is a JSON object with the following entries:

Key Type Description
id Number A unique identifier for this line item
line_item_number String Your unique identifier for this purchase order line item
product_sku String or Number SKU used to identify the product uniquely
cargo_ready_date String The cargo ready date for this line item
units Number The number of units for this line item
unit_cost String The cost per unit for this line item
booking_line_items Array<Booking Line Item> A list of the booked units and shipments associated with this line item

Booking Line Item

A Booking Line Item is a JSON object with the following entries:

Key Type Description
units Number The number of units for this line item
shipment_id Number The shipment id associated with this booking

Transportation Mode

The transportation mode for a purchase order can be one of the following strings:

Create


curl -v -X POST 'https://api.flexport.com/purchase_orders' \
  -H 'Accept:  application/vnd.flexport.v1' \
  -H 'Content-Type: application/json' \
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"' \
  -d '{"record": {"id":123, "name":"PO 1", "role":"buyer", "other_party_ref":"seller_1", "currency_code":"USD", "must_arrive_date":"2017-04-20", "cargo_ready_date":"2017-03-20", "transportation_mode":"ocean", "incoterm":"FOB", "memo":"Memo", "origin_port_ref":"origin_port_1", "destination_port_ref":"destination_port_1", "origin_location_ref":"origin_location_1", "destination_location_ref":"destination_location_1", "archived": false, "po_line_items":[ { "id":10, "line_item_number":1, "product_sku":"ABCD123", "cargo_ready_date":"2017-03-20", "units":50, "unit_cost":"10.5"}, {"line_item_number":2, "product_sku":"ABCD124", "cargo_ready_date":"2017-03-20", "units":170, "unit_cost":"40.5"}]}}'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8

{"record":
  {
    "id": 123,
    "name": "PO 1",
    "role": "buyer",
    "other_party_ref": "seller_1",
    "currency_code": "USD",
    "must_arrive_date": "2017-04-20",
    "cargo_ready_date": "2017-03-20",
    "transportation_mode": "ocean",
    "incoterm": "FOB",
    "memo": "Memo",
    "origin_port_ref": "origin_port_1",
    "destination_port_ref": "destination_port_1",
    "origin_location_ref": "origin_location_1",
    "destination_location_ref": "destination_location_1",
    "archived": false,
    "po_line_items": [
      {
        "line_item_number": 1,
        "product_sku": "ABCD123",
        "cargo_ready_date": "2017-03-20",
        "units": 50,
        "unit_cost": "10.5"
      },
      {
        "line_item_number": 2,
        "product_sku": "ABCD124",
        "cargo_ready_date": "2017-03-20",
        "units": 170,
        "unit_cost": "40.5"
      }
    ]
  }
}

You can create a new purchase order with a POST request. Upon success, the request will respond with a 200 and the newly created purchase order.

A request should have a json body that contains a single record as described below:

Purchase Order

Key Type Description
name* String Your unique identifier for this purchase_order
role* String Your role in this purchase order (buyer or seller)
other_party_ref* String Your reference string for the other party
currency_code* String The currency code being used in this purchase order
must_arrive_date String The must arrive date for this purchase order
cargo_ready_date String The cargo ready date for this purchase order
transportation_mode* Transportation Mode The transportation mode used for this purchase order
incoterm String The incoterm used for this purchase order
memo String Your notes or instructions on this purchase order
origin_port_ref String Your reference string for the origin port
destination_port_ref String Your reference string for the destination port
origin_location_ref String Your reference string for the origin location
destination_location_ref String Your reference string for the destination location
archived Boolean Whether the purchase order is archived
po_line_items* Array<Purchase Order Line Item> A list of the line items in this purchase order

* indicates that the attribute is required.

Purchase Order Line Item

A Purchase Order Line Item is a JSON object with the following entries:

Key Type Description
line_item_number String Your unique identifier for this purchase order line item
product_sku* String or Number SKU used to identify the product uniquely
product_name String Name of the product
cargo_ready_date String The cargo ready date for this line item
units Number The number of units for this line item
unit_cost String The cost per unit for this line item

* indicates that the atribute is required.

product_name is required on a Purchase Order Line Item if the product does not already exist.

Update


curl -v -X POST 'https://api.flexport.com/purchase_orders' \
  -H 'Accept:  application/vnd.flexport.v1' \
  -H 'Content-Type: application/json' \
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"' \
  -d '{"record": {"name":"PO 1", "role":"buyer", "other_party_ref":"seller_1",  "currency_code":"USD", "must_arrive_date":"2017-04-20", "cargo_ready_date":"2017-03-20", "transportation_mode":"ocean", "incoterm":"FOB", "memo":"Updated Memo", "origin_port_ref":"origin_port_1", "destination_port_ref":"destination_port_1", "origin_location_ref":"origin_location_1", "destination_location_ref":"destination_location_1", "archived": false, "po_line_items":[ { "line_item_number":1, "product_sku":15, "cargo_ready_date":"2017-03-20", "units":50, "unit_cost":"10.5"}, {"line_item_number":2, "product_sku":16, "cargo_ready_date":"2017-03-20", "units":170, "unit_cost":"40.5"}]}}'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8

{"record":
  {
    "name": "PO 1",
    "role": "buyer",
    "other_party_ref": "seller_1",
    "currency_code": "USD",
    "must_arrive_date": "2017-04-20",
    "cargo_ready_date": "2017-03-20",
    "transportation_mode": "ocean",
    "incoterm": "FOB",
    "memo": "Updated Memo",
    "origin_port_ref": "origin_port_1",
    "destination_port_ref": "destination_port_1",
    "origin_location_ref": "origin_location_1",
    "destination_location_ref": "destination_location_1",
    "archived": false,
    "po_line_items": [
      {
        "line_item_number": 1,
        "product_sku": "ABCD123",
        "cargo_ready_date": "2017-03-20",
        "units": 50,
        "unit_cost": "10.5"
      },
      {
        "line_item_number": 2,
        "product_sku": "ABCD124",
        "cargo_ready_date": "2017-03-20",
        "units": 170,
        "unit_cost": "40.5"
      }
    ]
  }
}

You can update a purchase order with a POST request. By default, the purchase order matching the name specified in the record will be replaced with your request body. You can specify the attribute to search on using the key query parameter (eg. https://api.flexport.com/purchase_orders?key=id). Supported attributes are id and name.

Upon success, the request will respond with a 200 and the replaced purchase order.

A request should have a json body that contains a single record as described below. If you actively wish to nullify a field, set the field to null.

Purchase Order

Key Type Description
id Number A unique identifier for this purchase_order
name String Your unique identifier for this purchase_order
role* String Your role in this purchase order (buyer or seller)
other_party_ref* String Your reference string for the other party
currency_code* String The currency code being used in this purchase order
must_arrive_date String The must arrive date for this purchase order
cargo_ready_date String The cargo ready date for this purchase order
transportation_mode* Transportation Mode The transportation mode used for this purchase order
incoterm String The incoterm used for this purchase order
memo String Your notes or instructions on this purchase order
origin_port_ref String Your reference string for the origin port
destination_port_ref String Your reference string for the destination port
origin_location_ref String Your reference string for the origin location
destination_location_ref String Your reference string for the destination location
archived Boolean Whether the purchase order is archived
po_line_items Array<Purchase Order Line Item> A list of the line items in this purchase order

* indicates that the attribute is required.

Only one of id and name is required, depending on which you key. If no key is provided, only name is required.

Purchase Order Line Item

Key Type Description
line_item_number String Your unique identifier for this purchase order line item
product_sku* String or Number SKU used to identify the product uniquely
product_name String Name of the product
cargo_ready_date String The cargo ready date for this line item
units Number The number of units for this line item
unit_cost String The cost per unit for this line item

* indicates that the attribute is required.

product_name is required on a Purchase Order Line Item if the product does not already exist.

Invoices

List invoices

curl -v -X GET 'https://api.flexport.com/invoices?status=all'
  -H 'Accept:  application/vnd.flexport.v1'
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8


{"records":  [
  {"amount_paid": "123.77",
   "currency": "USD",
   "due_date": "2016-01-01",
   "first_shared_at": "2015-12-13T21:53:11.728Z",
   "id": 4321,
   "invoice_id": "FLEX-12345-1",
   "lines": [{"amount": "1588.77",
               "category": "freight",
               "id": 111,
               "name": "Air Freight"},
              {"amount": "0.0",
               "category": "additional",
               "id": 112,
               "name": "Freight Insurance (Total)"},
              {"amount": "65.0",
               "category": "destination",
               "id": 113,
               "name": "Airline Terminal "},
              {"amount": "300.24",
               "category": "freight",
               "id": 114,
               "name": "Fuel Charge"},
              {"amount": "106.34",
               "category": "freight",
               "id": 115,
               "name": "Security Charge"},
              {"amount": "206.42",
               "category": "destination",
               "id": 116,
               "name": "Pickup & Delivery (Weight)"}],
   "shipment_id": "12345",
   "status": "paid",
   "total": "2266.77",
   "type": "Shipment"
  }]
}

This endpoint returns a response which contains a list of records. The status argument can be set to any of the statuses below or to ‘all’ to receive all invoices.

Result

Success

In the event of successful request you will receive a response with a status code of 200 with a JSON body that contains the following values.

Record

Key Type Description
id Number A unique identifier for your invoice
invoice_id String A human readable unique identifier for your invoice
currency String Currency code for this invoice.
first_shared_at String The date the invoice was shared with you
due_date String The date the invoice is due
total Number The total amount due
amount_paid Number The amount that has been paid so far
status Status The status of the invoice
type String The type of the invoice. Either ‘Shipment’ or ‘Client’
shipment_id Number The id of the shipment. Does not exist if invoice is of type ‘Client’
shipment_name String The name of the shipment. Does not exist if invoice is of type ‘Client’
lines Line A collection of line items that constitute the invoice.

Line

In the event of successful request you will receive a response with a status code of 200 with a JSON body that contains the following values.

Key Type Description
amount Number The amount of the line item
category Category The category of the line item.
id Number A unique identifier for a line item
name String A human readable identifier for a line item

Status

The status of an invoice can be one of the following:

Category

The category of a line item can be one of the following:

Products

List your products


# /products
curl -v -X GET 'https://api.flexport.com/products'
  -H 'Accept: application/vnd.flexport.v1'
  -H 'Authorization: Token token="41a08de1c61033008bb1998ae0c66ed3"'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"records": [
  {
    "category": "Apparel",
    "country_of_origin": "Vietnam",
    "hs_codes": [
      {
        "hs_code": "6205.20.2026",
        "region": "US"
      }
    ],
    "id": 30667,
    "name": "Polo Shirt (Large)",
    "product_properties": {
      "Size": "Large"
    },
    "sku": "TEX-2 L"
  }
]}

# /products/:id
curl -v -X GET 'https://api.flexport.com/products/30667'
  -H 'Accept: application/vnd.flexport.v1'
  -H 'Authorization: Token token="41a08de1c61033008bb1998ae0c66ed3"'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"record":
  {
    "category": "Apparel",
    "country_of_origin": "Vietnam",
    "hs_codes": [
      {
        "hs_code": "6205.20.2026",
        "region": "US"
      }
    ],
    "id": 30667,
    "name": "Polo Shirt (Large)",
    "product_properties": {
      "Size": "Large"
    },
    "sku": "TEX-2 L"
  }
}

You can get a list of all of your products by querying this endpoint. This endpoint returns a response which contains a list of records.

Result

In the event of successful request you will receive a response with a status code of 200 with a JSON body that contains the following values.

Key Type Description
id Number A unique identifier for this product defined by Flexport
sku String Your unique identifier for this product
name String A human-readable name for this product
category String A classification of your product
country_of_origin String The country of origin of this product
hs_codes HS Code The HS Codes for your product.
product_properties Object A JSON object of customizable key:value pairs

HS Codes

Key Type Description
hs_code String The HS Code for your product (e.g. “6205.20.2026”)
region String The region for this HS code. Currently only “US”, but more will be added.

Create


# CREATE /products
curl -v -X POST 'https://api.flexport.com/products'
  -H 'Accept: application/vnd.flexport.v1'
  -H 'Content-Type: application/json'
  -H 'Authorization: Token token="41a08de1c61033008bb1998ae0c66ed3"'
  -d '{"record":{"name":"Polo Shirt (Large)","sku":"TEX-2 L","country_of_origin":"Vietnam","category":"Apparel","hs_codes":[{"hs_code":"6205.20.2026","region":"US"}],"product_properties":{"Size":"X-Large"}}}'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"record":
  {
    "category": "Apparel",
    "country_of_origin": "Vietnam",
    "hs_codes": [
      {
        "hs_code": "6205.20.2026",
        "region": "US"
      }
    ],
    "id": 30667,
    "name": "Polo Shirt (Large)",
    "product_properties": {
      "Size": "Large"
    },
    "sku": "TEX-2 L"
  }
}

You can create a new product with a POST request. Upon success, the request will respond with a 200 and the newly created product.

A request should have a json body that contains a single record as described here

Update


# UPDATE /products/:id
curl -v -X PUT 'https://api.flexport.com/products/30667'
  -H 'Accept: application/vnd.flexport.v1'
  -H 'Content-Type: application/json'
  -H 'Authorization: Token token="41a08de1c61033008bb1998ae0c66ed3"'
  -d '{"record":{"id":30667,"name":"Polo Shirt (X-Large)","sku":"TEX-2 XL","country_of_origin":"China","category":"Apparel","hs_codes":[{"hs_code":"6205.20.2026","region":"US"}],"product_properties":{"Size":"X-Large"}}}'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"record":
  {
    "id": 30667,
    "category": "Apparel",
    "country_of_origin": "China",
    "hs_codes": [
      {
        "hs_code": "6205.20.2026",
        "region": "US"
      }
     ],
    "name": "Polo Shirt (X-Large)",
    "product_properties": {
      "Size": "X-Large"
    },
    "sku": "TEX-2 XL"
  }
}

You can update a product with a PUT request. Upon success, the request will respond with a 200 and the updated product.

A request should have a json body that contains a single record as described here

Update will only update fields that you include in the record. Any fields left out of the request will be left as is. If you actively wish to nullify a field, set the field to null.

Destroy


# DESTROY /products/:id
curl -v -X DELETE 'https://api.flexport.com/products/30667'
  -H 'Accept: application/vnd.flexport.v1'
  -H 'Authorization: Token token="41a08de1c61033008bb1998ae0c66ed3"'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{}

You can delete an existing product with a DELETE request. Upon success, the request will respond with a 200.

Webhooks

Configure webhooks

post '/payload' do
  request.body.rewind
  payload_body = request.body.read
  verify_signature(payload_body)
  push = JSON.parse(params[:payload])
  puts "I got some JSON: #{push.inspect}"
end

def verify_signature(payload_body)
  signature = 'sha1=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), ENV['SECRET_TOKEN'], payload_body)
  return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, request.env['HTTP_X_HUB_SIGNATURE'])
end

Webhooks can be created from your account settings

Secret Tokens

In order to verify that only requests coming from Flexport are allowed into your system, we require you to set a secret token for each of your endpoints. Flexport sends an X-Hub-Signature header with the value set as demonstrated on the right with each message. By verifying this header matches your expectations, we can ensure that only people with the secret token can send data to your endpoint.

Response

Flexport expects to receive an HTTP 200 response code from your endpoint. We will continue trying to deliver the message a number of times if we don’t receive one. To prevent time outs, it is wise to configure your endpoints to send a 200 and then do any long running processing on the data.

Payloads

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8
X-Hub-Signature:   sha1=b2b251cde69286cfbf62101a47ea47ca34b3132b

{
  "data": {},
  "type": "ping",
  "created_at": "2016-02-18T00:54:47.529Z"
}

The payload will be json, with the contents of the data field depending on the type of event being sent.

Event Types

ping

type: ping

data: {}

A test ping. These can be sent from your account settings to test if your endpoint is properly configured.

shipment event

This represents a shipment event, like the ones that would show up in a shipment on our website.

type: shipment_event.event_type

Key Type Description
shipment Shipment The shipment object corresponding to the appropriate shipment
message String (Optional) The message attached to the shipment event

Event Types

This is a non-exhaustive sampling of the types of shipment events you should expect to receive.

Ports

Search ports

curl -v -X GET 'https://api.flexport.com/ports?q=SFO&port_type=airport'
  -H 'Accept:  application/vnd.flexport.v1'
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8

{
  "records": [
    {
      "id": 567007,
      "name": "San Francisco International Airport, San Francisco, California, United States",
      "iata_code": "SFO",
      "lat": "37.623908",
      "lng": "-122.381592",
      "port_name": "San Francisco International Airport",
      "port_type": "airport",
      "country_code": "US"
    }
  ]
}

This endpoint returns a JSON object that contains a single field called records. Records is a list of ports. It comes back paginated.

Parameters

Key Type Value
q String A query string
page Number The page you want to pull down (defaults to 1)
per Number The number of ports you want to pull down (defaults to 15)
port_type String (Optional) The type of port (‘airport’, ‘seaport’, or ‘railport’)

Result

Success

In the event of successful request you will receive a response with a status code of 200 with a JSON body that contains a list called records, each of which will contain the following values.

Record

Key Type Description
id Number A unique identifier for the port
name String The full name of this port
iata_code String IATA code for a port. null for anything but IATA classified airports.
lat Number Latitude of the port
lng Number Longitude of the port
port_name String A shorter name for the port
port_type String “airport”, “seaport”, “railport” or “unknown_port”
country_code String The ISO_3166-1_alpha-2 code of the country the port is in

Network

List network places

curl -v -X GET 'https://api.flexport.com/network'
  -H 'Accept:  application/vnd.flexport.v1'
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8


{
  "records": [
    {
      "relationship_type": "self",
      "contact": {
        "phone": "123456789",
        "email": "email@email.com",
        "name": "Contact Person"
      },
      "addresses": [
        {
          "country_code": "US",
          "lat": "37.123345",
          "lng": "-74.133212",
          "id": 123,
          "city": "New York",
          "business_hours": "9-5",
          "name": "Some NY Warehouse",
          "street_address": "34 Park Ave.",
          "street_address2": "",
          "state": "NY",
          "contact": {
            "phone": "987654321",
            "email": "email@email.com",
            "name": "John"
          }
        }],
      "name": "Your Company"
    },
    {
      "relationship_type": "seller",
      "contact": {
        "phone": "136-1234-5678",
        "email": null,
        "name": null
      },
      "addresses": [
        {
          "country_code": "CN",
          "lat": "22.5500",
          "lng": "114.1000",
          "id": 551804,
          "city": "Shenzhen",
          "business_hours": null,
          "name": null,
          "street_address2": null,
          "state": null,
          "contact": {
            "phone": null,
            "email": null,
            "name": null
          },
          "street_address": "1234 Madison Ave"
        }
      ],
      "name": "Your Seller"
    }
  ]
}

This endpoint returns a response which contains a list of records. Each record is a company in your network. Each company has a list of addresses.

Result

Success

In the event of successful request you will receive a response with a status code of 200 with a JSON body that contains the following values.

Record

Key Type Description
relationship_type Relationship Type A string designating your relation to the company
contact Contact An object providing contact information for the company
addresses Address A list of addresses
name String The name of the company

Address

Key Type Description
id Number A unique identifier for an address
name String The given name of the address
lat Number Latitude of the address
lng Number Longtiude of the address
country_code String The ISO_3166-1_alpha-2 code of the country the port is in
city String City
street_address String The street address
street_address2 String The 2nd street address (often empty or null)
state String The state
contact Contact The contact for this location
business_hours String Human readable business hours for this business

Contact

A contact at a company

Key Type Description
name String A name
phone String A phone number
email String An email

Relationship Type

The relationship_type of a company on your network can be one of the following:

Create a company


# CREATE /network
curl -v -X POST 'https://api.flexport.com/network'
  -H 'Accept:  application/vnd.flexport.v1'
  -H 'Content-Type: application/json'
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'
  -d '{"record":{"name":"Company Name","relationship_type":"seller","contact":{"name":"Contact Name","email":"test@email.com","phone":"0123456789"}}}'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8

{"record": {
  "id": 12345,
  "name": "Company Name",
  "relationship_type": "seller",
  "contact":  {
    "name": "Contact Name",
    "email": "test@email.com",
    "phone": "0123456789"
  }
}}

You can create a new network company with a POST request. Upon success, the request will respond with a 200 and the newly created company.

Update a company


# UPDATE /network/:id
curl -v -X PUT 'https://api.flexport.com/network/12345'
  -H 'Accept:  application/vnd.flexport.v1'
  -H 'Content-Type: application/json'
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'
  -d '{"record":{"name":"Company Name","relationship_type":"seller","contact":{"name":"Contact Name","email":"test@email.com","phone":"0123456789"}}}'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8

{"record": {
  "id": 12345,
  "name": "Company Name",
  "relationship_type": "seller",
  "contact":  {
    "name": "Contact Name",
    "email": "test@email.com",
    "phone": "0123456789"
  }
}}

You can update a company with a PUT request. Upon success, the request will respond with a 200 and the updated product.

A request should have a json body that contains a single record as described here

Update will only update fields that you include in the record. Any fields left out of the request will be left as is. If you actively wish to nullify a field, set the field to null.

Create a network place


# UPDATE /network/:id
curl -v -X POST 'https://api.flexport.com/network/12345/create_address'
  -H 'Accept:  application/vnd.flexport.v1'
  -H 'Content-Type: application/json'
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'
  -d '{"record": {"external_ref": "external_ref", "state": "CA", "street_address": "Street Address", "street_address2": "Street Address 2", "contact": {"email": "test@test.com", "name": "Test Person", "phone": "01234"}, "city": "Test City", "name": "Test Address Name", "country_code": "US"}}'

A successful response to such a request results in:

HTTP/1.1 200 OK
Content-Type:  application/json; charset=utf-8

{"record": {
  "id": 1234,
  "country_code": "US",
  "state": "CA",
  "name": "Test Address Name",
  "city": "Test City",
  "street_address": "Street Address",
  "street_address2": "Street Address 2",
  "contact": {
    "name": "Test Person",
    "email": "test@test.com",
    "phone": "01234"
  },
  "external_ref": "external_ref"
}}

You can create a new network adderss with a POST request. Upon success, the request will respond with a 200 and the newly created address.

Currency Codes

List

curl -v -X GET 'https://api.flexport.com/currency_codes' \
  -H 'Accept:  application/vnd.flexport.v1' \
  -H 'Authorization:  Token token="41a08de1c61033008bb1998ae0c66ed3"'

The response to a successful request will be structured as follows:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"records": [
  {
    "code": "AED",
    "symbol": "د.إ",
    "name": "United Arab Emirates Dirham"
  },
  {
    "code": "ARS",
    "symbol": "$",
    "name": "Argentine Peso"
  },
  {
    "code": "AUD",
    "symbol": "$",
    "name": "Australian Dollar"
  }
]}

This endpoint will list all currency codes supported by Flexport. Each element in the array of records in the response will be as such:

Key Type Description
code String The currency code
name String The name of the associated currency
symbol String The symbol representing the currency

Errors

Each request type has specific errors that are detailed throughout the documentation. This is meant to be a general description of errors that could occur across all request types as well as a description of the common error response format.

Error Codes

The Flexport API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request has some type of problem not understood by a particular endpoint
401 Unauthorized – Your API key is likely invalid
404 Not Found – You either do not have permission or an entity/endpoint does not exist
405 Method Not Allowed – You tried to access an endpoint with an invalid method
406 Not Acceptable – You requested a format that isn’t json
429 Too Many Requests – Your request rate is too high. Try again later.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error":
  [
    "Name can't be blank",
    "Product is not valid",
  ]
}

All errors that include a response body have the same form. The response is a JSON object with the key error with an array value. The elements in the array are strings containing the error.