Getting Started

Flexport Logistics API provides access to the Flexport logistics network that powers all of our e-commerce operations, such as order fulfillment, order returns, freight, and parcel. With the Logistics API, you can create custom applications and integrations to access your Flexport account, or authorize Flexport-approved partner applications for that purpose.

The Logistics API is a REST API with the OpenAPI3 specification available at: https://logistics-api.flexport.com/logistics/api/2023-10/documentation/raw

To start using the Logistics API, you must have an active Flexport Portal account. To inbound physical inventory, ship orders, process returns or buy parcel labels, you'll also need to set up a billing account.

API Users

There are two primary user categories for the Logistics API:

User type Meaning within the API reference
You are a merchant if you use the API to develop an integration for your own business or shop.
You are a partner if you use the API to develop an application to serve Flexport merchants or your own customers.

Account Creation

Create a free Flexport Portal account. Complete the questions to create your account, and don't forget to add your business name. When asked to create a catalog, you can select "I'm not selling online yet".

Account Types

Account type Purpose
Production Used for fulfilling real orders with physical inventory.
Sandbox Used for testing fulfillment with simulated inventory and orders. Returns and Parcels do not support Sandbox at this time.

Production and Sandbox are completely isolated and separate Seller Portal accounts. Production account holds physical inventory and incurs costs when orders ship to customers.

Sandbox is an API test environment where you can test your application prior to running it against your production account. Inventory inbounded to the Sandbox account is simulated and auto-received, and orders may be placed against it that are also automatically shipped. Refer to Testing in Sandbox for more information.

Authentication and Authorization

To use the API, you will need an access token. Each access token carries permission scopes with it. This allows you to create one access token to access products, and another one to access orders, for example.

Creating Access Tokens

There are two ways to request an access token:

  1. Using the UI in Seller Portal -> Settings -> API Tokens.
  2. Using the API as described here

You must be an Administrator of your organization to manage access tokens.

Once issued, access tokens do not expire unless revoked by the Administrator.

Testing in Sandbox

Sandbox allows Flexport customers and partners using the Logistics API to test their applications without moving physical goods around.

Requesting Sandbox Account

To request a Sandbox account:

  • Register for a new separate account on Seller Portal
  • Reach out to Support and provide your account information to convert your account into a Sandbox account. (This may be self-served in the future).

Testing your application in Sandbox

After you have created the Sandbox account using the steps above, you can test your application against it.

Sandbox uses the same API endpoint as production. The API token serves as a pointer that allows the backend system to find the account you are accessing. Use the API token from the Sandbox account to work with Sandbox data. Sandbox and Production accounts are completely isolated from one another, as if they were accounts from separate customers.

Sample API Workflow

As an example, you can use this workflow to go from production creation to inbounding inventory and order placement in Sandbox:

  1. Create a product via the API
  • Be sure to include dimensions
  1. Ensure the product has dimensions and weight.
  • You can validate this inSeller Portal, if any are missing you can enter them manually.
  • In our production environment, all new products are measured on inbound and you are not required to provide dimensions - although you can.
  1. Create an inbound shipment using the API.
  • The inbound will automatically received within an hour.
  • Only inbounds created via the API will be auto-received (using Seller Portal UI for creating an inbound is not supported).
  1. Wait for the inbound to be auto-received
  1. Place an order via API
  • Order will automatically be picked, packed and shipped within an hour.

At this time, our sandbox environment only supports the happy-path use cases. We currently cannot test:

  • Lot & Expiration dates
  • Split shipments
  • Overage, shortage & damaged inbounds
  • Returns

Partner Program

Logistics API may be used by Merchants and by Partners. Either a Merchant or a Partner may develop a software application that uses the Logistics API.

Key difference between a Merchant and a Partner is that:

  • Merchant writes a software application that uses the Logistics API against their own account only.
  • Partner writes a more general software application that uses the Logistics API on behalf of multiple merchants that gave their consent.

Partner Registration

Currently partner registration is manual but may be self-served in the future.

If you wish to develop an application for use by one or more merchants, reach out to us to request a unique application ID and secret. Your software application must include a public API server that receives callbacks with the authorization code whenever a merchant authorizes it using the OAuth authorization_code flow. In response to callback, your application would exchange the one-time OAuth code for an API token.

Provide the following:

  • Detailed description of your business and what your software application will do.
  • Callback URI (registered in DNS) where your application will be receiving authorization codes.

You will receive your application ID and secret. You must use the application ID and secret as client credentials when when exchanging OAuth authorization code for an API token during OAuth token exchange.

Migration Guides

This section will guide you through migration from the Deliverr API V1.

Here are the key differences between the two APIs at a high level:

Difference Logistics API version 2023-04 Deliverr API version 1.0.0
OAuth 2.0, RFC6749 compliant Yes No
Release schedule Every 3 months Ad-hoc

A handful of identifiers have been renamed or added in the Logistics API. Refer to the tables, like the one below, in each of the following guides.

Changes in Deliverr API Logistics API
All resources productId (DSKU) logisticsSku

Access tokens

You must request new access tokens as described here when migrating from Deliverr API.

Inbounds

Changes in Deliverr API Logistics API
All resources productId logisticsSku
Inbounds shippingPlan shipment
Inbounds externalShippingPlanId N/A
Inbounds destination N/A
Inbounds caseQuantity N/A

In the Logistics API, inventory inbounding has been simplified and a number of new endpoints have been added. Refer to the Inbounds reference for additional details.

Key differences between the API are highlighted below:

  1. Shipments can be read individually by the id of the shipment or as a list by specifying a list of ids via the shipmentIds query parameter
  2. logisticsSku replaces productId as the identifier for the product being inbounded
  3. When creating a shipment, the fields externalShippingPlanId, destination and caseQuantity are no longer supported
  4. You cannot retrieve a shipment by an "external" shippingId.
  5. Prep services such as box content labels can be required when creating a shipment
  6. The GET labels endpoint in the Deliverr API has been replaced by an endpoint to request an expanded set of documents for the shipment here, which includes box content labels, shipping labels and bill of landing.

Products

Changes in Deliverr API Logistics API
All resources productId logisticsSku
Product msku merchantSku
Product externalProductId N/A
Inventory availableUnits available
Inventory N/A onHand
Inventory N/A unavailable

A few fundamental changes:

  • It is no longer necessary to link an alias to a product before use, as linking functionality is optional
  • For placing fulfillment orders, use logisticsSku instead of externalProductId in the list of lineItems
  • In the seller portal, your existing externalProductId mapping under the aliases section of a Product Detail page as "Deliverr API" will not be used in the Logistics API and will remain unchanged
  • You cannot update a product's dimensions (height, length, width, weight), units (lb/kg, in/cm), or category via the API

The retrieve inventoryretrieve inventory endpoint response contains a few new fields.

The retrieve warehouse details endpoint is a POST request instead of a GET. Instead of passing a list of productId in the productIds query parameter, you will now send a body in the following JSON format:

{
  "logisticsSKUs": [
    "DSKU1",
    "DSKU2",
    "DSKU3"
  ]
}

Bundles

The bundle endpoints remain semantically similar between the Deliverr API and the Logistics API. However, the bundle creation flow has changed between the APIs. The order endpoints in the Logistics API do not support fulfilling orders by bundleId. Merchants who wish to fulfill bundle orders in the logistics API have two options:

  • You manage the mapping of bundles to their definitions in your systems, which is an array of { logisticsSku, quantity }.
  • You define bundles via the API or the Seller Portal. Use the GetBundle endpoint to retrieve the bundle definition.

In both cases, you must use the logisticsSku and its total quantity when creating an order.

The following operations no longer exist in the Logistics API.

Deprecated Endpoints
PATCH LinkAliasToBundle
PATCH UnlinkAliasFromBundles
GET GetBundleByExternalBundleId

Orders

Changes in endpoint Deliverr API Logistics API
Create order externalProductId logisticsSku
Create order orderShipmentTime promisedShipByTime
Create order orderDeliverTime promisedDeliveryByTime
Create order shipToAddress address
Create order deliverDays deliveryDays
Create order N/A packingSlipUrl
Create order N/A duties
Create order createdAt N/A
Create order updatedAt N/A
Create order orderCreationTime N/A

The response payload for getting an order’s information has now changed. See the retrieve order response.

Reports

Beyond changes to the URIs, the report endpoints are a one-to-one mapping between the Deliverr API and the Logistics API.

Webhooks

Your webhook subscriptions must be recreated using the create webhook endpoint.

Common Resources

Besides following the OpenAPI 3.0 specification, below is a list of common resources and standards shared across the APIs.

Headers

The Logistics API makes use of the following custom HTTP headers.

Header field name in request in response description
x-correlation-id no yes UUID v4 tied to a request
idempotency-key yes no Can be any string, use for making POST or PATCH requests fault tolerant
idempotent-replayed no yes If included in the response, indicates a stored value was used to replay the request

Versioning

The Logistics API uses date based versioning for releases. Versions are declared explicitly in the Logistics API URI with a format of /logistics/api/{api_version}/{endpoint}. Stable releases follow the format of yyyy-mm. Experimental releases have an API version of unstable. For example:

/logistics/api/2023-04/orders
/logistics/api/unstable/orders

Release Notes

2024-04

Parcels API

  • getBulkParcelJob: This API retrieves details about a bulk parcel creation job.
  • createBulkParcelJob: Use this API to submit a bulk parcel creation job.

2024-01

API Sandbox (New)

  • API Sandbox may be used for testing fulfillment with simulated inventory and orders.

Partner OAuth (New)

  • Support for partners serving multiple Flexport customers has been added.

Outbounds Reserve Storage (New)

  • Outbounds API allows you to create outbound orders from reserve storage warehouses to fulfilment centres. The APIs also allow you to track the status of the reserve storage outbound orders and cancel them.

Inbounds

  • Update Create a shipment API to accept a shippingPlanName. This is the name that will appear in the Flexport Portal.
  • Update Get a shipment and Get a list of shipments APIs to support reading direct shipments that were created in Seller Portal.
  • InboundReceivedEvent documentation was updated to include DAMAGED state.

Products

  • New GetProductAliases API to list all aliases by logisticsSku.
  • New GetProductsByMerchantSku API to get a paginated list of products by merchantSku.
  • New CreateProductBarcode API to validate and assign a new barcode to a product by logisticsSku.

Orders

  • Update CreateOrder API to accept Flexport bundle SKUs.
  • Update CreateOrder API to take packingSlipUrl that overrides the default packing slip.
  • Flexport Fast Tags functionality has been clarified for CreateOrder API.
  • Events documentation updated to clarify the difference between Shipment.Shipped and Order.Shipped.

2023-10

Parcels API

  • Added customsInformation to create a parcel. You can now send parcels to international addresses and specify the relevant customs information.
  • Added customLabelFooterFields to create a parcel. This field lets you define a string to be placed on the footer of the shipping label.
  • Return new flexportTrackingUrl field when creating a parcel, retrieving a parcel, or retrieving parcel tracking events. This field can be used to track a package end-to-end through Flexport and final mile partner networks.

Inbounds API

  • Added shippingPlanName to create an inbounding shipment. This is the name that will appear in the Flexport Portal.
  • Added shippingPlanExternalId to create an inbounding shipment. This field is an external ID that can be used to link to/from other systems.
  • Return shippingPlanName and shippingPlanExternalId in getting an inbound shipment, or getting a list of inbound shipments.

2023-07

Products API

  • New API GetAllInventory. Get a paginated list of available inventory information for products.
  • New API GetProducts. Return a paginated list of products.

Parcels API

  • New API to get parcel tracking information (including sortation center events) by carrier tracking code
  • New API to cancel a parcel that was previously created.

2023-04

  • Initial public beta release of the Logistics API

unstable

The "unstable" version contains code experimental changes, developer previews, and new features. However, endpoints can always change and may update with breaking changes without notice.

Errors

When an API error occurs, the HTTP response includes a three-digit HTTP status code with additional information returned as a problem+json object, for example:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://logistics-api.flexport.com/logistics/api/2023-04/documentation/spec#section/Errors/404-Not-Found",
 "title": "Not Found",
 "detail": "Cannot find order 49201824029",
 "instance": "92e04577-c56b-47b9-b075-62096165a0ce",
}

In addition to the three-digit HTTP status code, some errors carry a six-digit error code
that provides additional detail about the specific error condition. For example 405004 error code refers to Invalid scopes and is documented here.

400 Bad Request

Bad Request.

Possible Causes

  • Incorrect HTTP method used.
  • Non-existent URL path used.
  • Malformed syntax in the request.
  • Missing a required parameter.
  • Input on the request did not pass validation.
  • The resource to be modified has moved into a state that is no longer valid.

Possible Solutions

  • Retry the request after correcting errors in the request and confirming it's valid.
  • Verify if the resource to be modified exists and is in a valid state.

401 Unauthorized

The access token is invalid.

Possible Causes

  • No valid access token provided.

Possible Solutions

  • Check to ensure that the access token is valid.

403 Forbidden

Access token does not have permission to perform the requested operation.

Possible Causes

  • Access token provided is not authorized to perform the requested operation.

Possible Solutions

  • Check to ensure that the scope of the access token is sufficient to perform the requested operation.
  • Create and use a new access token that has the required scope.

404 Not Found

The requested object cannot be found.

Possible Causes

  • The identifier pointing to the request is incorrect.
  • The specified resource is no longer available.
  • You do not have access to the specified resource.

Possible Solutions

  • Check that the specified resource exists.

409 Conflict

The object with the same identifier already exists.

Possible Causes

  • Resource was already created, but the request is attempting to create it again.

Possible Solutions

  • Check that the resource identifier is unique.
  • Use idempotency-key when creating resources.

422 Unprocessable Content

The request is malformed.

Possible Causes

  • Request contains invalid data or syntax errors.

Possible Solutions

  • Check the payload for inconsistencies or errors.

429 Too Many Requests

Too many requests in a given amount of time ("rate limiting").

Possible Causes

  • Too many requests were made in a short period of time that exceed the API rate limit allowed.

Possible Solutions

  • Try again later. We recommend an exponential backoff of your requests.
  • Refer to the Retry-After header for the number of seconds to wait before retrying the request.

423 Locked

Access to the Logistics API is locked and denied.

Possible Causes

  • Flexport Portal account may be frozen and/or deactivated.

Possible Solutions

5XX Internal Server Error

An internal error has occurred while processing the request (these are uncommon).

Possible Causes

  • The request is incorrect and cannot be processed.
  • The server is currently unable to handle the request.

Possible Solutions

  • Verify that the request is correct and retry it.
  • Retry the request at a later time.

405001 Invalid redirect URI

The redirect URI specified as a callback for OAuth authorization is invalid.

Possible Causes

  • Redirect URI must be https://deliverr.com if identity is used as the client ID.
  • Redirect URI must be exactly the same URI as the one registered with the client ID provided.

Possible Solutions

  • Verify that the redirect URI is correct.

405002 Invalid client_id

Invalid client_id.

Possible Causes

  • The client ID provided is invalid. The client ID must be identity or a valid client ID registered with Flexport.

Possible Solutions

  • Submit a valid client ID.

405003 Missing scopes

Scopes were not provided.

Possible Causes

  • Scope parameter was not provided in the request.

Possible Solutions

  • Check to ensure the request includes scopes. For all available scopes see OAuth.

405004 Invalid scopes

Some of the scopes provided are invalid. For all available scopes see OAuth.

Possible Causes

  • Scope parameter was provided in the request, but the scope values are invalid.
  • Incorrect separator was used to separate scopes.

Possible Solutions

  • Check to ensure that scopes requested are known and valid. For all available scopes see OAuth.

405005 Invalid code

The one-time authorization code provided is invalid, expired, or has already been used.

Possible Causes

  • Authorization code has already been used.
  • Authorization code has expired because it was requested longer than a few minutes ago.
  • Authorization code is invalid.

Possible Solutions

  • Restart the OAuth flow to receive a new authorization code.

407001 Invalid order status

Operation cannot proceed, because order is in a state that does not allow it.

Possible Causes

  • Order retry was requested, however the original order was successful.

Possible Solutions

  • Ensure that the order is in the correct state, e.g. if order is being retried the order state should be Canceled.