Products API Tutorial
Table of contents
The Flexport Products API allows you to get a list of all products for a client, create a product, retrieve a single product, as well as updating a product.
Endpoints
GET /products
POST /products
GET /products/
PATCH /products/id
The following images show the equivalent in-app feature as it appears on the Flexport App's Create Product screen:
In order to use the products API, no preliminary setup is required. However, if you intend to use the compliance feature of product creation (providing HS classification/codes), the HS Code/Country combination you provide must be known to Flexport Customs. Prior to providing this level of detail via the products endpoint, please consult with Flexport operations.
Check out the list of supported parameters before you get going.
You will create a product using POST over the endpoint index. The unique reference for your product will be its sku. Be careful thought because additional updates with the same sku will be rejected as duplicates.
We'll make an HTTP POST https://api.flexport.com/products
As mentioned, the unique reference for your product will be its sku.
curl -X "POST" "https://api.flexport.com/products" \
-H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
-H 'Flexport-Version: 3' \
-H 'Content-Type: application/json' \
-d $'{
"_object": "/product",
"name": "Acme Wallpaper Blue Glam",
"sku": "ACME-33x3d3",
"product_category": "Wall Furnishings",
"country_of_origin": "",
"product_properties": [
{
"_object": "/product/property",
"type": "Seller Item Number",
"value": "23/18D"
},
{
"_object": "/product/property",
"type": "Color",
"value": "Blue"
},
{
"_object": "/product/property",
"type": "Division",
"value": "Dec Acc"
},
{
"_object": "/product/property",
"type": "Department",
"value": "Wallpaper"
},
{
"_object": "/product/property",
"type": "Sub-Department",
"value": "Wallpaper"
},
{
"_object": "/product/property",
"type": "Category",
"value": "Wallpaper"
}
],
"classifications": [
{
"_object": "/product/classification",
"codes": ["4816.90.00.00"],
"region": "CA"
}
]
}'
Sample Response:
{
"_object": "/api/response",
"self": "https://api.flexport.com/products",
"version": 2,
"data": {
"_object": "/product",
"id": 7832800,
"sku": "ACME-33x3d3",
"name": "Acme Wallpaper Blue Glam",
"description": null,
"client_verified": false,
"archived_at": null,
"product_category": "Wall Furnishings",
"country_of_origin": "",
"product_properties": [
{
"_object": "/product/property",
"type": "Color",
"value": "Blue"
},
{
"_object": "/product/property",
"type": "Seller Item Number",
"value": "23/18D"
},
{
"_object": "/product/property",
"type": "Division",
"value": "Dec Acc"
},
{
"_object": "/product/property",
"type": "Department",
"value": "Wallpaper"
},
{
"_object": "/product/property",
"type": "Sub-Department",
"value": "Wallpaper"
},
{
"_object": "/product/property",
"type": "Category",
"value": "Wallpaper"
}
],
"hs_codes": [],
"classifications": [
{
"_object": "/product/classification",
"codes": [
"4816.90.00.00"
],
"region": "CA"
}
],
"suppliers": []
},
"error": null
}
If you know the object id of your product, you may retrieve it using GET, for example:
curl -X "GET" "https://api.flexport.com/products/7832800" \
-H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
-H 'Flexport-Version: 3' \
-H 'Accept: application/json' \
You may also query the index using any of the supported parameters.
For example, to search by sku you would query by f.sku, for example:
curl -X "GET" "https://api.flexport.com/products?f.sku=ACME-33x3d3" \
-H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
-H 'Flexport-Version: 3' \
-H 'Accept: application/json' \
Sample Response:
{
"_object": "/api/response",
"self": "https://api.flexport.com/products?f.sku=ACME-33x3d3",
"version": 2,
"data": {
"_object": "/api/collections/paginated",
"prev": null,
"next": null,
"total_count": 1,
"data": [
{
"_object": "/product",
"id": 7832800,
"sku": "ACME-33x3d3",
"name": "Acme Wallpaper Blue Glam",
"description": null,
"client_verified": false,
"archived_at": null,
"product_category": "Wall Furnishings",
"country_of_origin": "",
"product_properties": [
{
"_object": "/product/property",
"type": "Color",
"value": "Blue"
},
{
"_object": "/product/property",
"type": "Seller Item Number",
"value": "23/18D"
},
{
"_object": "/product/property",
"type": "Division",
"value": "Dec Acc"
},
{
"_object": "/product/property",
"type": "Department",
"value": "Wallpaper"
},
{
"_object": "/product/property",
"type": "Sub-Department",
"value": "Wallpaper"
},
{
"_object": "/product/property",
"type": "Category",
"value": "Wallpaper"
}
],
"hs_codes": [],
"classifications": [
{
"_object": "/product/classification",
"codes": [
"4816.90.00.00"
],
"region": "CA"
}
],
"suppliers": []
}
]
},
"error": null
}
You can update an existing product using an HTTP PATCH over the /products/:id URL. You may obtain the Flexport id by either storing it on a POST, or by querying the endpoint using your sku (?f.sku) prior to using PATCH.
Example (here we change only the color of the product under the properties):PATCH https://api.flexport.com/products/7832800
curl -X "PATCH" "https://api.flexport.com/products/7832800" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Flexport-Version: 3" \
-H "Content-Type: application/json" \
-d $'{
"_object": "/product",
"sku": "ACME-33x3d3",
"product_properties": [
{
"_object": "/product/property",
"type": "Color",
"value": "Electric Blue"
}
]
}'
Response:
{
"_object": "/api/response",
"self": "https://api.flexport.com/products/7832800",
"version": 2,
"data": {
"_object": "/product",
"id": 7832800,
"sku": "ACME-33x3d3",
"name": "Acme Wallpaper Blue Glam",
"description": null,
"client_verified": false,
"archived_at": null,
"product_category": "Wall Furnishings",
"country_of_origin": "",
"product_properties": [
{
"_object": "/product/property",
"type": "Color",
"value": "Electric Blue"
},
{
"_object": "/product/property",
"type": "Seller Item Number",
"value": "23/18D"
},
{
"_object": "/product/property",
"type": "Division",
"value": "Dec Acc"
},
{
"_object": "/product/property",
"type": "Department",
"value": "Wallpaper"
},
{
"_object": "/product/property",
"type": "Sub-Department",
"value": "Wallpaper"
},
{
"_object": "/product/property",
"type": "Category",
"value": "Wallpaper"
}
],
"hs_codes": [],
"classifications": [
{
"_object": "/product/classification",
"codes": [
"4816.90.00.00"
],
"region": "CA"
}
],
"suppliers": []
},
"error": null
}
It is best practice to query the endpoint by your sku before deciding to perform a POST or PATCH for create/update operations.
You may query the index using any of the supported parameters.
As an example, to search by sku you would query by f.sku, for example:
curl -X "GET" "https://api.flexport.com/products?f.product_properties.color=blue" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Flexport-Version: 3" \
-H "Accept: application/json" \
Sample Response:
{
"_object": "/api/response",
"self": "https://api.flexport.com/products?f.sku=ACME-33x3d3",
"version": 2,
"data": {
"_object": "/api/collections/paginated",
"prev": null,
"next": null,
"total_count": 1,
"data": [
{
"_object": "/product",
"id": 7832800,
"sku": "ACME-33x3d3",
"name": "Acme Wallpaper Blue Glam",
"description": null,
"client_verified": false,
"archived_at": null,
"product_category": "Wall Furnishings",
"country_of_origin": "",
"product_properties": [
{
"_object": "/product/property",
"type": "Color",
"value": "Blue"
},
{
"_object": "/product/property",
"type": "Seller Item Number",
"value": "23/18D"
},
{
"_object": "/product/property",
"type": "Division",
"value": "Dec Acc"
},
{
"_object": "/product/property",
"type": "Department",
"value": "Wallpaper"
},
{
"_object": "/product/property",
"type": "Sub-Department",
"value": "Wallpaper"
},
{
"_object": "/product/property",
"type": "Category",
"value": "Wallpaper"
}
],
"hs_codes": [],
"classifications": [
{
"_object": "/product/classification",
"codes": [
"4816.90.00.00"
],
"region": "CA"
}
],
"suppliers": []
}
]
},
"error": null
}
On occasion, things don’t always proceed as you expect. Various HTTP error codes, along with an exception JSON object, are returned to help you build your exception handling routines.
An example of an Error Response is shown below.
{
"_object": "/api/error",
"status": 400,
"code": "invalid_pagination",
"message": "Invalid Sort Direction. allowed values: desc, asc"
}
You’ll want to use the status and message fields to handle exceptions. Let’s take a look at possible values in those fields.
- SKU Product with SKU XXXX already exists. Please update SKU field or search for the existing SKU.
- Missing property XXX
- Could not find HS Code XXX.XX.XX.XX for CA
- invalid HS code data provided
- invalid regions provided: XX
- data provided for the following regions multiple times: XX