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.

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.

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".

• You can access the Products, Webhooks and Reports API immediately regardless of billing status.
• To use the Parcels or Returns API, your account must meet certain criteria. To inquire, submit a support ticket.
• All other APIs require setting up billing in the Flexport Seller Portal.

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.

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.

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

2. 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.

2. 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).

3. Wait for the inbound to be auto-received

• This can take up to an hour (this time may be lowered in the future)
• Inventory counts for your product will be updated in Seller Portal after inbound is received

4. 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

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.

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.

In order for your application to receive Merchant consent and the API token, you would direct the merchant to the OAuth authorization_code flow that has your application ID, as well as the scopes that your application requires. You do not need to include the callback URI, because it is known to us since your application is registered.

For example, if your application requires read access to products and orders and the application ID is 01HKBBNEVYKM0D84E63MMYN022 the URI is: https://logistics-api.flexport.com/logistics/api/2023-10/oauth/authorize?response_type=code&scope=read_logistics_products+read_logistics_orders&client_id=01HKBBNEVYKM0D84E63MMYN022

When Merchant visits this URL they'll be shown a Consent page displaying your application name and required access (scopes). If they click through to agree to use your application, your application server will receive the OAuth code on the callback URI that you registered with your application.

Your application would then exchange the OAuth authorization code for an API token during OAuth token exchange. For client credentials, you would submit your application ID 01HKBBNEVYKM0D84E63MMYN022 and the secret you received. In addition to the API token, the response will include the logisticsAccountId of the merchant.

Your application must treat each API token with utmost care and store in a secure encrypted location and encrypt and protect it while in transit.

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

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

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.

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"
  ]
}

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

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.

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

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

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

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

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

Orders API

• createOrder: Update API to allow drop ship orders
• getOrder: Update API to get drop ship details for orders

Parcels API

• getBulkParcelJob: This API retrieves details about a bulk parcel creation job.
• createBulkParcelJob: Use this API to submit a bulk parcel creation job.
• Update getParcel, getParcelTracking, getParcelTrackingByTrackingCode and createParcel to return an option field carrierBarcode.
• Update flexportTrackingUrl datatype from string to URL
• Add isReturn field in the createParcel API request (backported into 2024-04 version)

Orders API

• Add TIKTOK as a supported source marketplace.

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.

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.

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.

• Initial public beta release of the Logistics API

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.

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.

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.

The access token is invalid.

Possible Causes

• No valid access token provided.

Possible Solutions

• Check to ensure that the access token is valid.

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.

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.

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.

The request is malformed.

Possible Causes

• Request contains invalid data or syntax errors.

Possible Solutions

• Check the payload for inconsistencies or errors.

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.

Access to the Logistics API is locked and denied.

Possible Causes

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

Possible Solutions

• Contact Flexport Support

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.

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.

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.

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.

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.

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.

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.