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.

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.

The API has two audiences: merchants, who build integrations for their own business or shop, and partners, who build applications that serve Flexport merchants or their 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

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 is issued with one or more permission scopes that define which resources and operations it can access. You can issue separate tokens scoped to different resources — for example, one token scoped only to products and another scoped only to orders — to follow the principle of least privilege.

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

When creating a token, select the permission scopes it should carry — each scope grants access to a specific resource family in either read-only or read-write mode. The required scope for each operation is listed on its reference page under Authorizations.

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

This quickstart walks you through verifying your access token and making your first API request. You'll confirm your token is wired up correctly before moving on to creating products, inbound shipments, and orders.

1. Get an access token

The Logistics API authenticates requests with a bearer token. In Seller Portal, go to Settings → API Tokens and click Create Token. Copy the token — you'll use it in the next step.

If you don't have a Flexport account yet, follow Account Creation first. For the full token flow, including partner (OAuth) tokens, see Creating Access Tokens.

2. Set your token

export FLEXPORT_TOKEN="YOUR_API_TOKEN"

3. Call the API

GET /logistics/api/2026-02/warehouses/active

Examples below use API version 2026-02. Substitute the version you target in production — see Versioning.

curl "https://logistics-api.flexport.com/logistics/api/2026-02/warehouses/active" \
  -H "Authorization: Bearer $FLEXPORT_TOKEN"

[
  "ATL1",
  "LAX2",
  "RNO1"
]

{
  "status": 401,
  "type": "https://docs.logistics-api.flexport.com/2026-02/#section/Errors/401-Unauthorized",
  "title": "Unauthorized",
  "instance": "92e04577-c56b-47b9-b075-62096165a0ce",
  "code": 401,
  "message": "Unauthorized"
}

{
  "status": 403,
  "type": "https://docs.logistics-api.flexport.com/2026-02/#section/Errors/403-Forbidden",
  "title": "Forbidden",
  "instance": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "code": 403,
  "message": "Forbidden"
}

The request invokes GetActiveWarehouses and requires the read_logistics_warehouses scope. It returns the warehouse codes (for example, ATL1) available to your account — the same identifiers that appear on shipment and order responses to indicate the fulfillment facility. You can filter by country using the countryCode query parameter (US, NL).

A 200 OK with this array confirms the token is valid and correctly scoped. A 401 Unauthorized indicates an invalid, malformed, or expired token; a 403 Forbidden indicates the token is valid but missing the read_logistics_warehouses scope. See Errors for resolution.

4. Build your integration

With the token verified, the typical integration order is:

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 in Seller 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.

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

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

5. 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 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/2026-02/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:

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.

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

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.

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.

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.

Every access token is issued with one or more permission scopes. Each scope grants access to a specific resource family in either read-only or read-write mode. Requests that target an operation whose required scope is not present on the token are rejected with 403 — see 403 Forbidden. When requesting an OAuth token, omitted or unknown scopes return 405003 Missing scopes or 405004 Invalid scopes.

The per-operation scope requirement is declared on each endpoint's reference page under Authorizations. When requesting a partner (OAuth) token, pass the scopes as a +-separated list in the scope query parameter of the AuthorizationRedirect call.

The unstable version exposes additional scopes covering experimental endpoints (freight, sales channels, uploads). Refer to the unstable reference for the full list; these scopes are not yet available on stable versions.

Follow the principle of least privilege: issue separate tokens with the narrowest scope set each integration needs, rather than a single token with every scope.

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

Authentication and API Tokens

• Token expiration: Merchant (non-3PL) tokens expire after one year from creation and existing tokens are given a one-year grace period. Partner (3PL) tokens do not expire.
• Expired tokens will automatically be marked INACTIVE
• Rotate tokens in Settings → API Tokens before they expire.

Events and Webhooks

• Order.Submitted: This event and webhook is generated when Order is Submitted to system.
• Order.PickingStarted: This event and webhook is generated when Order picking has started at the warehouse.
• Order.Packed: This event and webhook is generated when Order is Packed at the warehouse.
• Order.Delivered: This event and webhook is generated when Order is Delivered to destination.
• Shipment.Submitted: This event and webhook is generated when Shipment is Submitted to system.
• Shipment.PickingStarted: This event and webhook is generated when Shipment picking has started at the warehouse.
• Shipment.Packed: This event and webhook is generated when Shipment is Packed at the warehouse.
• Shipment.Delivered: This event and webhook is generated when Shipment is Delivered to destination.

Bundles API

• getBundles: This API retrieves list of bundles with cursor-based pagination.

Parcels API

• createMasterCarton: This API creates master carton labels in bulk.
• linkMasterCarton: API to link a master carton barcode to list of parcel tracking codes.

Outbounds API

• getOrderByExternalId: This API gets the order details based on the external ID provided by the seller.
• getShipmentAttachmentUrl: This API generates a pre-signed URL that can be used to upload an attachment for a specific outbound shipment.

Inbounds API

• getStorageWarehouses: API to get a list of storage warehouses that can store products.

• Update createAShipment API to:

  1. Allow creating reserve storage shipments
  2. Pick nearest crossdock location while creating forwarding shipments
  3. Allow specifying sellerLPNs for each package

• Update getInboundingShipment API to allow support storage shipments

• Update getInboundingShipments API to allow support for storage shipments

• get_inbounds_warehouses: API to get a list of storage warehouses and Fulfillment Centres

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.

Inbounds API

• getInboundsWarehouses: This API Fetches List of Warehouse Details for Both DTC & RS based on the request parameters.

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://docs.logistics-api.flexport.com/2026-02/#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 or expired.

Possible Causes

• No valid access token provided.
• The token has expired (merchant tokens expire after one year by default).

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

• Contact Flexport Support

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.