API Release Note
Release note are structured as follows:
- Categories of change for an API:
- New feature - new feature added to API
- Structure change - change on data structure returned by API
- Data change - data content changes returned by API
- Deprecation - API functionalities which will be deprecated
- Removal - API functionalities which will be removed soon
- Impacted: Which API will be impacted by the changes
- Release date: Date when changes will be deployed in production
- Description: The content of changes
Current Release
- Orders: new status
partial_refunded
- Category of change: Non breaking data change
- Impacted: Orders API
- Release date: 2023-12
- Description:
- The lengow order status
partial_refunded
is added and will be available for Veepee at first.
- The lengow order status
- New meta in order meta:
shipping_deadline
- Category of change: Non breaking data change
- Impacted: Orders API
- Release date: 2023-12
- Description:
- This attribute in the order.meta object will be provided for some Mirakl marketplaces at first. See Mirakl-Orders-API-News-December-2023-New-field-available
Released
Orders list: Date filter improvement - 2023-07-25
- Category of change: Data change
- Impacted: Orders API
- Release date: 2023-07-25
- Description:
- The default date filter is now applied when none of the provided date filters is valid.
- Previously no filter was applied on time in this case, causing heavy unbounded queries.
- As a reminder, the default date filter is "ordered during the previous 7 days".
- As a consequence, the orders count in the response has changed if you are using an incorrect date filter.
Orders:
max_shipping_date
- 2022-12-20- Category of change: Structure change
- Impacted: Orders API
- Release date: 2022-12-20
- Description: Adding
max_shipping_date
field to order lines (packages.cart). This information is provided by some marketplaces.
Add account's catalog endpoint - 2021-12-03:
- Category of change: New Feature
- Impacted : Catalog APIs
- Release date: 2021-12-03
- Description: New API at
http://api.lengow.io/v3/catalog/account/
has been added, it provides a way to fetch catalog's information of an account and its child accounts.
Add account's feed endpoint - 2021-12-03:
- Category of change: New Feature
- Impacted : Feed APIs
- Release date: 2021-12-03
- Description: New API at
http://api.lengow.io/v3/feed/account/
has been added, it provides a way to fetch feed's information of an account and its child accounts.
Example :
{
"results": [
{
"marketplace": "amazon_fr",
"account_id": 1,
"marketplace_country_iso2": "FR",
"marketplace_order_id": "408-6677687-12234567",
"anonymized": false,
"order_types": [
{
"type": "is_delivered_by_marketplace",
"label": "AFN"
}
]
}
]
}
Add order types nodes - 2019-08-19:
- Category of change: Structure change
- Impacted : Orders APIs
- Release date: 2019-08-19
- Description: news nodes "order_types" and "orderline_types" are added at
order level and cart level respectively.
It provides an uniform way of characterizing an order's feature.
Current possible keys for order_type.type are :
- is_express: Needs express shipping, for example in Amazon Prime program
- is_delivered_by_marketplace: Order or product is fulfilled by marketplace
- is_business: B2B order
- is_prime: Amazon-specific
Add new amount fields - 2019-03-25
- Category of change: Structure change
- Impacted: Orders APIs
- Release date: 2019-03-25
- Description: By default, all amount fields are in the merchant account's currency. For example, if an US merchant has orders in amazon FR, even the marketplace is amazon fr which uses Euros as currency, these orders amount fields are converted to dollar. So we added these new fields which contain the account in marketplace currency: "original_total_order", "original_total_tax", "original_amount","original_tax","original_discount", "original_shipping", "original_discount", "original_commission", "original_processing_fee", "original_currency".
Example
curl https://api.lengow.io/v3.0/preprocessing/job/?account_id=1&catalog=1
- New API for preprocessing - 2018-05-22
- Category of change: New feature
- Impacted: N/A
- Release date: 2018-05-22
- Description: A new API for launching preprocessing task.
- Remove category_name field - 2017-12-18
- Category of change: Structure change
- Impacted: Orders APIs
- Release date: 2017-12-18
- Description: The category_name field was added to display the merchant category name. Actually, as *category * field contains well the merchant category name indeed of category id before, we will remove the *category_name *.
curl https://api.lengow.io/v3.0/marketplaces?marketplace=admarkt
{
"admarkt": {
"package": "mp_admarkt",
"country_iso_a2": "NL",
"country": "NLD",
"name": "Admarkt",
"legacy_code": "admarkt",
"orders": {
"carriers": {},
"actions": {},
"status": {}
},
"logo": "cdn/partners//_.jpeg",
"description": "Admarkt is a Dutch marketplace which lets you generate qualified traffic to your online shop.",
"homepage": "http://www.marktplaatszakelijk.nl/admarkt/"
}
}
- Add new filter to Marketplaces APIs - 2017-12-18
- Category of change: New feature
- Impacted: Marketplace APIs
- Release date: 2017-12-18
- Description: New filter marketplace was added
Exemple of delivery dictionary after correction:
Example
{
"delivery": {
"id": 295324,
"type": "billing",
"first_line": "25, Allée des Paix",
"zipcode": "38000",
"city": "GRENOBLE",
"company": null,
"civility": "Mr",
"first_name": "Tony",
"last_name": "DUPOND",
"second_line": null,
"complement": null,
"phone_home": null,
"phone_office": null,
"phone_mobile": null,
"full_address": null,
"full_name": null,
"email": null,
"metas": null,
"state_region": null,
"common_country_iso_a2": "FR",
"trackings": []
}
}
Fix order actions api response format - 2017-08-25
- Category of change: Structure change
- Impacted: Orders Actions API
- Release date: 2017-10-16
- Description: When the post data has an error, the orders actions API returns two different formats response. Here are two examples:
FORMAT 1 : [ "Value for tracking_number is required in the data field." ]
FORMAT 2 :
{ "account_id": [ "Ce champ est obligatoire." ] }
We will keep the format 2 and remove the format 1.
Overview
Content-Type and Accept Headers
curl https://api.lengow.io/v3.0/orders/ -X OPTIONS --header "Accept: application/json"
If you want to change the returned data format, you can set the Accept
header.
The server will respond you with the given format and change the Content-Type
header.
By default, the format is "application/json".
To get all accepted format, you can use the OPTIONS
method.
API types
Basic type | Description or aliases |
---|---|
String | String |
Integer | Integer |
Decimal | Decimal, Float |
Boolean | Boolean |
Array | Array, List |
Object | Object, Json |
Country | Depending on ressource, countries are specified as two (ISO 3166-2) or three characters |
Date | All date/time values are specified in ISO 8601 |
Currency | All currencies are specified as three characters (ISO 4217) |
None | None, null, nothing |
All monetary amounts like prices are specified as decimal number.
When the API accepts or returns several types, the format is as followed Array, String
.
HTTP Response Codes
Below is a non-exhaustive list of HTTP response codes used by the API. For more information, see the List of HTTP code status.
Code | Text | Description |
---|---|---|
200 | OK | Success |
201 | Created | The request has been fulfilled, a new resource has been created. |
202 | Accepted | The request needs asynchronous action to create the resource, but is correct and as been accepted. |
400 | Bad Request | The request has not been processed because of a client error (bad request syntax, invalid arguments...). See accompanying message for more information. |
401 | Access not granted | Authentication is required for this request and has failed. |
403 | Forbidden | User is not allowed to access this resource. |
404 | Not Found | The request resource could not be found. |
429 | Request limitation reached | Too many requests have been made in a too short amount of time. |
502 | Bad gateway | The service is unreachable, probably due to capacity problem. We are improving our systems to deal with peak hours. In the meantime, please try to query outside of peak hours (automated processing tend to use exact hour and half-hours) |
503 | Service Unavailable | The service is (temporarily) unavailable. Please retry later. |
504 | Gateway Timeout | The service is overloaded. We are improving our systems to deal these peak hours. In the meantime, please try to query outside of peak hours (automated processing tend to use exact hour and half-hours) |
530 | Logical Error | The request has failed probably due to bad input parameters (catalog that does not exist, invalid search rules...). See accompanying message for more information. |
540 | Technical Error | The request has failed due to an internal error. See accompanying message for more information. |
Authentication
You need to authenticate yourself before making any request on the Lengow API.
Get a token
curl "https://api.lengow.io/access/get_token" -X POST --data "access_token=XXXXX&secret=XXXXX"
{"token": "6b7280eb-e7d4-4b94-a829-7b3853a20126", "account_id": 1}
First, you'll need to get a token. Each token has a lifetime of 3600 seconds.
POST https://api.lengow.io/access/get_token
Parameter | Required | Description |
---|---|---|
access_token | Yes | Access token of the application |
secret | Yes | Secret of the application |
Make a request
curl https://api.lengow.io/v3.0/account/show?account_id=1 --header "Authorization: 6b7280eb-e7d4-4b94-a829-7b3853a20126"
Once you have your token, all your API request will need a Authorization
header.
Catalogs
Technical Guidelines
Stay in good standing as a Lengow Source Partner by meeting all of Lengow's technical requirements for your integration type.
Definition
In Lengow platform, a source can either be used globally or partially:
- Globally: as a main catalog
- Partially: to enrich a main catalog
Pre-requisites
A source contains at least a product ID and a product attribute and each row represents a single product.
- Each product must be clearly identified by a unique ID
- Each product must have at least one category
1. Sources format
1.1 CSV format
Example of CSV source accepted by Lengow
ID_PRODUCT;NAME_PRODUCT;REFERENCE_PRODUCT;MANUFACTURER;CATEGORY;DESCRIPTION;PRICE_PRODUCT;PRICE_REDUCTION;POURCENTAGE_REDUCTION;QUANTITY;EAN;URL_PRODUCT;IMAGE_PRODUCT;DELIVERY_PRICE;PARENT_ID;REDUCTION_FROM;REDUCTION_TO;PRODUCT_TYPE;PRODUCT_VARIATION;CURRENCY;COLOR
10;title 1;TEDDYno;brand_name;CLOTHING > COAT > TRENCH;description1;149;71;52.35;3;;https://site.com/product/10;https://site.com/product/10.jpg;0.00;10;10/01/2019 14:01;22/01/2019 23:59;parent;Color,size;EUR;Noir
10_581;title 1;TEDDYno T56;brand_name;CLOTHING > COAT > TRENCH;description1;149;71;52.35;0;3,61E+12;https://site.com/product/10_581;https://site.com/product/10_581.jpg;0.00;10;10/01/2019 14:01;22/01/2019 23:59;child;Color,size;EUR;Noir
10_580;title 1;TEDDYno T54;brand_name;CLOTHING > COAT > TRENCH;description1;149;71;52.35;2;3,61E+12;https://site.com/product/10_580;https://site.com/product/10_580.jpg;0.00;10;10/01/2019 14:01;22/01/2019 23:59;child;Color,size;EUR;Noir
10_579;title 1;TEDDYno T52;brand_name;CLOTHING > COAT > TRENCH;description1;149;71;52.35;4;3,61E+12;https://site.com/product/10_579;https://site.com/product/10_579.jpg;0.00;10;10/01/2019 14:01;22/01/2019 23:59;child;Color,size;EUR;Noir
11;title 2;TEDDY beige;brand_name;CLOTHING > COAT > TRENCH;description2;149;71;52.35;11;;https://site.com/product/11;https://site.com/product/11.jpg;0.00;11;10/01/2019 14:01;22/01/2019 23:59;parent;Color,size;EUR;Beige
11_569;title 2;TEDDYbg 46;brand_name;CLOTHING > COAT > TRENCH;description2;149;71;52.35;11;3,61E+12;https://site.com/product/11_569;https://site.com/product/11_569.jpg;0.00;11;10/01/2019 14:01;22/01/2019 23:59;child;Color,size;EUR;Beige
11_570;title 2;TEDDYbg 48;brand_name;CLOTHING > COAT > TRENCH;description2;149;71;52.35;0;3,61E+12;https://site.com/product/11_570;https://site.com/product/11_570.jpg;0.00;11;10/01/2019 14:01;22/01/2019 23:59;child;Color,size;EUR;Beige
11_571;title 2;TEDDYbg 50;brand_name;CLOTHING > COAT > TRENCH;description2;149;71;52.35;0;3,61E+12;https://site.com/product/11_571;https://site.com/product/11_571.jpg;0.00;11;10/01/2019 14:01;22/01/2019 23:59;child;Color,size;EUR;Beige
CSV (formatted text) is the preferred format. Accepted delimiters are :
- pipe
- comma
- semi-colon
- tab
1.2 XML format
Example of XML source accepted by Lengow
<?xml version="1.0" encoding="ISO-8859-1" ?>
<products>
<product>
<id>1</id>
<sku>155842</sku>
<title>title 1</title>
<description>description 1</description>
<product_link>http://site.com/product/155842</product_link>
<img_link>http://site.com/product/155842.png</img_link>
<brand>brand 1</brand>
<category>Categrory 1 > sub category 1</category>
<price>150.90</price>
<stock>15</stock>
</product>
<product>
<id>2</id>
<sku>255474</sku>
<title>title 2</title>
<description>description 2</description>
<product_link>http://site.com/product/255474</product_link>
<img_link>http://site.com/product/255474.png</img_link>
<brand>brand 1</brand>
<category>Categrory 1 > sub category 2</category>
<price>50.50</price>
<stock>6</stock>
</product>
<product>
<id>3</id>
<sku>255954</sku>
<title>title 3</title>
<description>description 3</description>
<product_link>http://site.com/product/255954</product_link>
<img_link>http://site.com/product/255954.png</img_link>
<brand>brand 1</brand>
<category>Categrory 2 > sub category 1</category>
<price>10.30</price>
<stock>5</stock>
</product>
</products>
The XML format is supported but in a very simplified way. An XML node should represent a collection of product nodes where each XML tag represents at the same level an attribute of the product.
1.3 JSON format
Example of JSON source accepted by Lengow
{
"date": "xxxxxx",
"products": {
"product": [
{
"id": "1",
"sku": "155842",
"title": "title 1",
"description": "description 1",
"product_link": "http://site.com/product/155842",
"img_link": "http://site.com/product/155842.png",
"brand": "brand 1",
"category": "Categrory 1 > sub category 1",
"price": "150.90",
"stock": "15"
},
{
"id": "2",
"sku": "255474",
"title": "title 2",
"description": "description 2",
"product_link": "http://site.com/product/255474",
"img_link": "http://site.com/product/255474.png",
"brand": "brand 1",
"category": "Categrory 1 > sub category 2",
"price": "50.50",
"stock": "6"
},
{
"id": "3",
"sku": "255954",
"title": "title 3",
"description": "description 3",
"product_link": "http://site.com/product/255954",
"img_link": "http://site.com/product/255954.png",
"brand": "brand 1",
"category": "Categrory 2 > sub category 5",
"price": "10.30",
"stock": "5"
}]
}
}
JSON is supported but in a very simplified way (no tree structure). During indexing of the source, the node of the products collection, "products" in the example, will have to be provided
2. Source protocols
2.1 HTTP, HTTPS
Both HTTP and HTTPS protocols are supported. For security reasons, provide HTTPS access. Access can be protected by a user/password pair (Basic Authentication).
Basic Authentication URL example:
https://user:password@www.example.com/
2.2 SSH et SFTP
SSH (and SFTP) protocols are supported, authentication is done by a user/password pair. Public key authentication is not currently supported.
2.3 FTP
The FTP protocol is supported, but for security reasons, choose SFTP. FTPS (FTP over SSL) is not supported.
3. Source Content
A source as qualified as possible is a quick win for our common merchants. With a high qualified source they will be able to send their products faster to any marketplaces but also to fully use all our functionalities like Insights (our products and market analysis tool).
A source fully imported in Lengow is named “catalog”. This catalog is the result of one or multiple combination of sources. In the end, a merchant needs to make sure that his catalogs contain at least the following fields:
- Unique_ID (mandatory)
- Expected value type: Alphanumeric
- Example: 1235RES56_1 (maximum of 25 characters)
- Category
- Expected value type: Alphanumeric
- Example: High tech > television > television LCD > 100 Hertz (maximum of 250 characters)
- Title
- Expected value type: Alphanumeric
- Example: Samsung 100 Hertz LCD Television
- Description
- Expected value type: Alphanumeric
- Example: television LCD 100 Hertz Samsung, 47 pouces...
- Price
- Expected value type: Numeric
- Example: 799.90
- Quantity_in_Stock
- Expected value type: Numeric
- Example: 23
- Product_URL
- Expected value type: Url
- Example: http://mysite.com/product.html
- URL_image
- Expected value type: Url
- Example: http://mysite.com/product_image.jpg (make sure the url is publicly accessible. Lengow doesn’t host images.)
- GTIN/EAN/UPC
- Expected value type: Numeric
- Example: 1234567891011
- ID_parent (A common identifier for all the variations of a product)
- Expected value type: Alphanumeric
- Example: 1235RES56
- Product_Type (use values “child”, “parent” or “simple”)
- Expected value type: Text
- Example: child
- Brand
- Expected value type: Alphanumeric
- Example: SAMSUNG
- Delivery_costs
- Expected value type: Numeric
- Example: 5.00
- Delivery_time
- Expected value type: Numeric
- Example: 12
4. Best Practice
- Categories:
- Breadcrumbs format is recommended
- Use the symbols “>” or “/” or “|” (Example of values: Shoes > Men's Shoes > sneakers)
- Otherwise use one field per category level.
- Never insert special characters (accents, %, /, or other symbols) in field titles.
- Never change the product unique IDs once integrated in Lengow
- Never change the field titles of the source once integrated. Never remove a field that is already being used in the platform. You can however add as many fields/columns as you like.
- All field titles in your product catalog must be unique. Every header must also be unique.
External Sources partners
Pre-requisites before developing a connector to push catalog data into Lengow
As part of a partnership with Lengow, a connector can be developed (by Lengow or by you) to allow your merchants to export their product catalogue data to Lengow. These developments will require access to your APIs, so before starting any developments, here are some points to note:
- Your APIs respect authentication standards (e.g. Oauth2, Basic Auth, etc.).
- Your APIs are usable via the HTTPS protocol.
- Your APIs are documented, versioned and sandbox testable.
- The call quota to your APIs is compatible with frequent catalog indexing.
- The methods of your APIs available allow us to obtain the complete catalog in a minimum of calls
Indeed, for performance reasons, it is difficult to make several calls per product to obtain all the attribute values of the product. The calls will only be made to retrieve a fully qualified source.
The most efficient exchange between us would be to provide the CSV catalog as a streamed or paged stream.
See Also
General source structure expected
Feeds
Orders
Specific order type reference | Description |
---|---|
Package | Informations about package, its delivery and product |
Address | Informations about the address |
Lengow status | Informations about possible order statuses |
Payment | Informations about payment, its date and status |
BuyerTax | Informations about buyer tax |
Tax | Informations about marketplace process to handle taxes |
Ordered product | Informations about one of the order lines |
Orders Status
Each marketplace have their own statuses. In Lengow, all these status are mapped to a Lengow status
.
List of all Lengow statuses :
Status | Allowed action | Description |
---|---|---|
new | None | Order was created but no action are available for now. |
waiting_acceptance | accept,refuse | The merchant has to accept the order. |
refused | None | The order was refused by the merchant. |
accepted | None | The order has been accepted by the merchant and waiting the marketplace authorization for shipping. |
waiting_shipment | ship | The merchant has to ship the order. |
shipped | None | The order is waiting the final marketplace validation for closing. |
closed | None | The order is closed, no more action are available. |
canceled | refund | The order was canceled. Depending on marketplace, you can refund the order. |
refunding | None | The refund demand is waiting the marketplace validation. |
refunded | None | Like closed status, the order is closed and no more action are available. |
partial_refunded | None | Similar to refunded , but not all the lines have refunded status. |
pickup_to_prepare | None | The merchant has to prepare the pick up. |
to_pickup | None | The order is ready for pick up. |
pickup_completed | None | The order has been picked up by the buyer. |
pickup_canceled | None | The pick up has been canceled. |
to_refund | refund | The merchant has to refund the order. |
Simple call :
curl https://api.lengow.io/v3.0/orders/?account_id=1
Get orders
GET https://api.lengow.io/v3.0/orders/
This API allows you to retrieve your orders.
With pagination :
curl https://api.lengow.io/v3.0/orders/?account_id=1&page=5&page_size=50
Pagination
The result is paginated and different arguments can be provided to manage this pagination.
Field | Type | Default | Description |
---|---|---|---|
page | Integer | 1 | The page number |
page_size | String | 100 | Maximum 100. Number of results by page |
Ordering
With ordering :
curl https://api.lengow.io/v3.0/orders/?account_id=1&ordering=marketplace,-updated_at
You can control the ordering of results with the ordering
parameter. For reversing the ordering, your can prefix your field by -
.
The default ordering is marketplace,-marketplace_order_date,-imported_at
.
List of supported ordering fields:
Argument | Type |
---|---|
marketplace | String |
marketplace_order_id | String |
merchant_order_id | String |
lengow_status | String |
marketplace_status | String |
marketplace_order_date | Date |
imported_at | Date |
updated_at | Date |
Filtering
With filtering :
curl https://api.lengow.io/v3.0/orders/?account_id=1&marketplace=menlook
You can filter the result with differents filters.
account_id
is a mandatory filter.
By default, the marketplace_order_date_from
filter is set to current day - 7 days
.
You can search a specific order by its marketplace_order_id
by providing
a couple of filters (marketplace_order_id
- marketplace
).
This couple is mandatory, in other case the API will use the
default filter (order date in the 7 previous days range
).
List of supported fields:
Filter | Type |
---|---|
account_id | Integer |
marketplace | String |
marketplace_order_id | String |
merchant_order_id | String, None to get empty values |
lengow_status | String |
marketplace_status | String |
marketplace_order_date_from | Date |
marketplace_order_date_to | Date |
imported_from | Date |
imported_to | Date |
updated_from | Date |
updated_to | Date |
The expected date format is ISO 8601 (including the timezone offset).
A short date format YYYY-MM-DD
will work, but you can't rely on the timezone to have a precise filter.
Changing the currency
With set_currency :
curl https://api.lengow.io/v3.0/orders/?account_id=1&set_currency=USD
By default, all amount fields are returned in your account's currency.
If you want to change the currency, you can use the set_currency
parameter. The value must be specified as three characters (ISO 4217).
An example of returned orders :
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"marketplace": "amazon_uk",
"account_id": 1,
"marketplace_country_iso2": "GB",
"marketplace_order_id": "order1",
"merchant_order_id": null,
"marketplace_status": "Shipped",
"lengow_status": "shipped",
"workflow_rank": 6,
"marketplace_order_date": "2019-03-22T17:54:34.369000Z",
"total_order": 809.2900000000001,
"total_tax": "134.45",
"shipping": 2.6,
"discount": 0,
"commission": "-56.47",
"processing_fee": null,
"currency": {
"iso_a3": "EUR",
"symbol": "€",
"name": "Euro"
},
"original_currency": {
"iso_a3": "GBP",
"symbol": "£",
"name": "British Pound"
},
"original_total_order": 701.25,
"original_total_tax": "116.50",
"original_shipping": 2.25,
"original_discount": 0,
"original_commission": "-48.93",
"original_processing_fee": null,
"original_total_buyer_amount": 1.00,
"original_total_buyer_tax": 1.55,
"original_buyer_currency": "EUR",
"comments": null,
"invoice_number": null,
"invoice_url": null,
"payments": [
{
"id": 1,
"checkout": null,
"status": null,
"type": "Other: Standard",
"settled_at": null,
"payment_terms": null,
"channel_order_marketplace": 1
}
],
"packages": [
{
"cart": [
{
"id": 1,
"marketplace_order_line_id": "line1",
"marketplace_product_id": "product1",
"merchant_product_id": {
"field": "ID_PRODUCT",
"id": "Product1"
},
"feed_id": 1,
"marketplace_package_id": null,
"marketplace_status": "Shipped",
"lengow_status": "shipped",
"title": "Product TEST",
"category": null,
"url_product": null,
"url_image": null,
"order_line_meta": {
},
"amount": "806.69",
"tax": "134.45",
"discount": null,
"shipping": "2.60",
"original_refunded_amount": "0.00",
"refunded_amount": "0.00",
"original_amount": "699.00",
"original_tax": "116.50",
"original_discount": null,
"original_shipping": "2.25",
"quantity": 1,
"max_shipping_date": "2019-03-25T11:48:09.071000Z",
"created_at": null,
"updated_at": null,
"original_buyer_tax": null,
"original_buyer_amount": null,
}
],
"delivery": {
"id": 1,
"type": "delivery",
"first_line": "1 Rue de la Paix",
"zipcode": "44",
"city": "Nantes",
"company": null,
"civility": null,
"first_name": null,
"last_name": null,
"second_line": null,
"complement": null,
"phone_home": null,
"phone_office": null,
"phone_mobile": null,
"full_address": null,
"full_name": "Dupont",
"email": "test@lengow.amazon.co.uk",
"metas": null,
"state_region": "",
"common_country_iso_a2": "GB",
"trackings": [
{
"number": null,
"method": "Standard",
"carrier": null,
"url": null,
"is_delivered_by_marketplace": true,
"parcel_weight": null,
"shipped_at": null,
"relay": {
"name": null,
"id": null,
"type": null
},
"marketplace_order_line_ids": [
"line1"
]
}
]
}
}
],
"billing_address": {
"id": 2,
"type": "billing",
"first_line": null,
"zipcode": "44",
"city": "Nantes",
"company": null,
"civility": null,
"first_name": null,
"last_name": null,
"second_line": null,
"complement": null,
"phone_home": null,
"phone_office": null,
"phone_mobile": null,
"full_address": null,
"full_name": "Dupont",
"email": "test@lengow.amazon.co.uk",
"metas": null,
"state_region": "",
"common_country_iso_a2": "GB"
},
"contact_address": null,
"imported_at": "2019-03-22T20:05:35.196060Z",
"updated_at": "2019-03-25T11:48:09.071000Z",
"order_meta": {
"checksum": "fffffffggghghhgu"
},
"tax": {
"order_tax_id": "T4X-1D",
"is_marketplace_deemed_supplier": true,
"tax_electronic_portal_type": "OSS",
"tax_electronic_portal_id": "OSS-1234",
"marketplace_eori_number": "EORI-5555",
"buyer_tax": {
"type": "VATIN",
"id": "123789",
},
},
"anonymized": false
}
]
}
Results
Field | Type | Description |
---|---|---|
count | Integer | Number of orders |
next | String | Link to the next page |
previous | String | Link to the previous page |
results | Array | List of orders |
Order object
Field | Type | Description |
---|---|---|
marketplace | String | Marketplace code |
account_id | Integer | Account ID |
marketplace_order_date | Date | Order date in UTC |
marketplace_country_iso2 | Country | Marketplace country. |
marketplace_order_id | String | Marketplace identifier of the order |
lengow_status | Lengow status | Lengow status |
marketplace_status | String | Marketplace status. Can be the same value than lengow_status. |
total_order | Decimal | Order price (shipping price and taxes included) |
total_tax | Decimal | Order tax |
commission | Decimal | Marketplace commission |
processing_fee | Decimal | Processing fees paid by the buyer |
shipping | Decimal | Total shipping amount paid by the buyer. Order shipping fees + Sum of order lines shipping fees. |
discount | Decimal | Total discount amount on this order. Order discount fees + Sum of order lines discount fees. |
currency | Currency | Currency of the merchant account |
original_currency | Currency | Currency of the marketplace |
original_total_order | Decimal | Order price (shipping price and taxes included) in marketplace currency |
original_total_tax | Decimal | Order tax in marketplace currency |
original_shipping | Decimal | Total shipping amount paid by the buyer. in marketplace currency |
original_discount | Decimal | Total discount amount on this order. in marketplace currency |
original_commission | Decimal | Marketplace commission in marketplace currency |
original_processing_fee | Decimal | Processing fees paid by the buyer in marketplace currency |
original_total_buyer_amount | Decimal | Total price as paid by the buyer |
original_total_buyer_tax | Decimal | Total tax as paid by the buyer |
original_buyer_currency | String | Currency of the buyer |
comments | String, Array | Comments of the buyer |
invoice_number | String | Invoice number |
invoice_url | String | Invoice URL |
billing_address | Address | Billing address |
contact_address | Address | Contact address |
payments | Array | Informations about payments |
packages | Array | List of the order packages |
order_meta |
Object | Order metadata which are specific by marketplace. If not present, a "null" value will be present |
tax | Tax | Informations about tax |
anonymized | Boolean | True when the address data is anonymized. (According to RGPD, we hide personal data for the orders older than 6 months. |
Package object
A package group all line of an order by delivery address.
Field | Type | Description |
---|---|---|
cart | Array | List of ordered products |
delivery | Address | Marketplace product identifier |
Ordered product
Field | Type | Description |
---|---|---|
marketplace_order_line_id | String | Marketplace order line ID |
marketplace_product_id | String | Marketplace product identifier |
merchant_product_id.id | String | Merchant product ID |
merchant_product_id.field | String | Source of merchant product ID |
marketplace_package_id | String | Marketplace package ID |
marketplace_status | String | Marketplace status of the line |
lengow_status | Lengow status | Lengow status of the line |
title | String | Merchant's product title |
category | String | Merchant's product category |
url_product | String | Merchant's product URL |
url_image | String | Merchant's product image (main) |
amount | Decimal | Total price of the line (product price * quantity) |
shipping | Decimal | Shipping fees for the product |
tax | Decimal | Total tax amount of the line |
discount | Decimal | Total discount amount of the line |
original_refunded_amount | Decimal | Refunded amount for the product in the marketplace currency |
refunded_amount | Decimal | Refunded amount for the product |
original_amount | Decimal | Total price of the line (product price * quantity) in marketplace currency |
original_shipping | Decimal | Shipping fees for the product in marketplace currency |
original_tax | Decimal | Total tax amount of the line in marketplace currency |
original_discount | Decimal | Total discount amount of the line in marketplace currency |
quantity | Integer | Ordered quantity |
max_shipping_date | Date | shipping deadline in UTC |
created_at | Date | Created date in UTC |
updated_at | Date | Updated date in UTC |
original_buyer_amount | Decimal | Item price as paid by the buyer |
original_buyer_tax | Decimal | Item tax as paid by the buyer |
Address object
Field | Type | Description |
---|---|---|
company | String | Company |
civility | String | Civility |
first_name | String | Firstname |
last_name | String | Lastname |
full_name | String | Fullname |
first_line | String | First line of the address |
second_line | String | Second line of the address |
complement | String | Address complement |
zipcode | Decimal | Zipcode |
city | Decimal | City |
phone_home | Decimal | Home phone number |
phone_office | Decimal | Office phone number |
phone_mobile | Integer | Mobile phone number |
full_address | Address | Full address |
String | ||
common_country_iso_a2 | Country | Country |
Tracking object
Field | Type | Description |
---|---|---|
number | String | Tracking number |
method | String | Civility |
carrier | String | Carrier |
url | String | Tracking URL |
is_delivered_by_marketplace | Boolean | Is the package delivered by marketplace ? (Amazon FBA for example) |
parcel_weight | Decimal | Package weight |
shipped_at | Date | Shipping date |
relay.id | String | Relay ID |
relay.name | String | Relay name |
relay.type | String | Relay type |
Payment object
Field | Type | Description |
---|---|---|
id | Integer | Unique identifier |
checkout | String | |
status | String | Marketplace's status for the payment |
type | String | Type of payment (example : Paypal) |
settled_at | Date | Is the package delivered by marketplace ? (Amazon FBA for example) |
Tax object
Field | Type | Description |
---|---|---|
order_tax_id | String | The relevant marketplace tax ID for the order and customs declaration. If the marketplace has collected the tax on the order |
is_marketplace_deemed_supplier | Boolean | Identifies whether the marketplace is responsible for collecting and has collected tax on the order or not |
tax_electronic_portal_type | String | Indicate the type of tax identifier of the marketplace. The tax identifier type will vary by country/region |
tax_electronic_portal_id | String | Indicate the tax identifier of the marketplace |
marketplace_eori_number | String | The marketplace EORI (Economic Operators Registration and Identification number) for customs declaration. If the marketplace has collected the tax on the order. EORI number = SIRET en France par exemple. = identifiant fiscal de l’entreprise |
buyer_tax | BuyerTax | Buyer tax informations |
BuyerTax object
Field | Type | Description |
---|---|---|
type | String | This value identifies the type of tax ID that was supplied by the buyer during the checkout process |
id | String | This value is the actual tax ID for the buyer. The type of tax ID is shown in the Type field |
Set Merchant Order ID
curl https://api.lengow.io/v3.0/orders/moi/ -X PATCH -H "Content-Type: application/json" --data
{
"account_id": 1,
"merchant_order_id": ["123456789"],
"marketplace": "marketplace_name",
"marketplace_order_id": "1234-ABC"
}
PATCH https://api.lengow.io/v3.0/orders/moi/
You can import your owns order identifiers in the Lengow systems.
Request
Parameter | Type | Description |
---|---|---|
account_id | String | Your Lengow account ID |
marketplace_order_id | String | order ID |
marketplace | String | The marketplace code of the order |
merchant_order_id | Array | Your merchant order ID |
Response
If your request was successful, the order object will be send.
Get all actions on orders
Simple call :
curl https://api.lengow.io/v3.0/orders/actions/?account_id=1
GET https://api.lengow.io/v3.0/orders/actions/
Filtering
You can filter the result with different filters.
account_id
is a mandatory filter.
With filtering :
curl https://api.lengow.io/v3.0/orders/actions/?account_id=1&marketplace_order_id=123456-ABC&marketplace=darty
List of supported filters:
Filter | Type |
---|---|
id | Integer |
account_id | Integer |
marketplace | String |
marketplace_order_id | String |
action_type | String |
processed | Boolean |
queued | Boolean |
tracking_number | String |
carrier | String |
line | String |
created_from | Date |
created_to | Date |
updated_from | Date |
updated_to | Date |
errors | String |
Result
Field | Type | Description |
---|---|---|
id | Integer | Lengow unique ID for the action |
account_id | Integer | Account ID |
marketplace | String | Marketplace code |
marketplace_order_id | String | Marketplace order ID |
action_type | String | Action type |
processed | Boolean | Is the action processed by marketplace ? |
queued | Boolean | Lengow still trying to make this action on the marketplace. |
tracking_number | String | Tracking number |
carrier | String | Carrier |
line | String | Line ID |
created_at | Date | Creation date of the action |
updated_at | Date | Date of the last action's update |
errors | String | Returned error. To have the final error, you should wait that queued becomes false. |
You can track the status of each action with "queued" and "processed" fields.
"queued" is true when the action is waiting for processing (or retrying on failure), and false when it is treated
"processed" is true when the action has been successful.
Available action types
Name | Description |
---|---|
accept | Accept the order |
refuse | Refuse the order |
ship | Ship the order |
cancel | Cancel the order |
refund | Refund the order |
partial_cancel | Partial cancellation of order |
set_delivery_date | Inform of order's delivery date (currently only available for El Corte Ingles) |
set_eligible_shipping_methods | Retrieve eligible shipping methods for current order (only available for Amazon) |
buy_shipment_label | Buy a shipment label (only available for Amazon) |
pickup_ready | Inform that an order is ready to be picked up (only available for eBay) |
pickup_complete | Inform that an order has been picked up (only available for eBay) |
pickup_cancel | Cancel a click & collect order (only available for eBay) |
pickup_refund | Refund a click & collect order (only available for eBay) |
Available actions depends on marketplace. Please refer you to the marketplace API.
Create an action on an order
curl https://api.lengow.io/v3.0/orders/actions/ -X POST -H "Content-Type: application/json" --data
{
"marketplace_order_id": "1234-ABC",
"account_id": 1,
"marketplace": "menlook",
"action_type": "ship",
"tracking_number": "123456",
"tracking_url": "http://www.ups.com/track?trackNums=123456",
"carrier": "ups",
"line": "1234-ABC-LINE"
}
POST https://api.lengow.io/v3.0/orders/actions/
With this API, you can make actions on your orders.
These actions will be sent asynchronously to the partner, and retried three times on failure.
Parameter | Required | Type | Description |
---|---|---|---|
marketplace_order_id | True | String | Order identifier of the marketplace |
account_id | True | Integer | Your account ID |
marketplace | True | String | The marketplace name |
action_type | True | String | Action type |
Depending on marketplace and action, some parameters are conditional and need to be included or to have specific values. Please refer to the marketplace API.
Parameter | Required | Type | Description |
---|---|---|---|
tracking_number | Conditional | String | Tracking number |
tracking_url | Conditional | String | Tracking URL (if not tracking_number) |
carrier | Conditional | String | Carrier |
line | Conditional | String | Line ID for partial action |
Marketplaces
Get marketplace informations
Simple call :
curl https://api.lengow.io/v3.0/marketplaces/
GET https://api.lengow.io/v3.0/marketplaces/
Marketplace code
All keys of the result are a Marketplace code
used by others API.
Always refers you to this API to get this code.
A Marketplace code
is unique and must match this regexp : [a-Z0-9-_]
Filtering
With filtering :
curl https://api.lengow.io/v3.0/marketplaces/?account_id=1
curl https://api.lengow.io/v3.0/marketplaces/?marketplace=darty
curl https://api.lengow.io/v3.0/marketplaces/?marketplace=darty&account_id=1
You can use the optionnal account_id
filter to only get your marketplaces, or marketplace
to get only one marketplace information:
Filter | Required | Description |
---|---|---|
account_id | No | To filter your marketplaces |
marketplace | No | To get only the specified marketplace information |
Result
Result json :
{
"name": "Boulanger",
"logo": "http://blog.boulanger.fr/wp-content/uploads/2010/10/logo-boulsign.jpg",
"legacy_code": "boulanger",
"description": "Launched at the end of 2014, the household electronics expert Boulanger has a rich range of items, and welcomes niche products. With brick-and-mortar experience spanning over 50 years, Boulanger now offers its expertise to internet users, and its large assortment of SKUs promises a quality audience.",
"country": "FRA",
"homepage": "http://www.boulanger.com/",
"orders": {
"status": {
"canceled": [
"CANCELED"
],
"closed": [
"RECEIVED",
"CLOSED"
],
"refunded": [
"REFUNDED"
],
"accepted": [
"WAITING_DEBIT",
"WAITING_DEBIT_PAYMENT"
],
"shipped": [
"SHIPPED"
]
},
"carriers": {
"DHL": {
"label": "DHL"
},
"Chronopost": {
"label": "Chronopost"
}
},
"actions": {
"ship": {
"status": [
"waiting_shipment"
],
"optional_args": [
"carrier",
"carrier_name",
"tracking_url"
],
"args_description": {
"tracking_url": {
"accept_free_values": true,
"depends_on": {
"operator": "allOf",
"conditions": [
{
"key_path": {
"root": "order",
"path": "order_meta.delivery_type",
},
"function": "equals",
"value": "PARCEL"
}
]
}
},
"carrier_name": {
"accept_free_values": true
}
},
"args": [
"tracking_number"
]
},
"accept": {
"status": [
"waiting_acceptance"
],
"optional_args": [
"line"
],
"args_description": {},
"args": []
},
"refuse": {
"status": [
"waiting_acceptance"
],
"optional_args": [
"line"
],
"args_description": {},
"args": []
}
}
}
}
Field | Type | Description |
---|---|---|
name | String | Marketplace name |
country | Country | Marketplace country |
description | String | Marketplace description (with HTML) |
homepage | String | Homepage of marketplace's website |
logo | String | Marketplace logo (URL) |
orders.status | Object | Mapping between lengow's status (keys) and marketplace's status (values) |
orders.carriers | Object | All carriers available |
orders.actions | Object | Informations about each actions (based on lengow's actions) |
Detail of orders.actions
Field | Type | Description |
---|---|---|
orders.actions.status .args |
String | Mandatory arguments |
orders.actions.status .optional_args |
String | Optional arguments |
orders.actions.status .args_description |
String | Description of arguments |
.args_description.field_name .depends_on |
Object | Some argument values may depend on the order data or other arguments sent during the action call. |
orders.actions.status .status |
String | Allowed status for this action |
Detail of depends_on fields / Conditional order action arguments
Field | Type | Description |
---|---|---|
depends_on.operator | String | Defines how many of the conditions should be respected. Values in oneOf, anyOf, allOf |
depends_on.conditions | Array | Informations about the specific field values |
depends_on.key_path | Object | Informations about where is located the condition data |
depends_on.key_path.root | String | Defines the source of the data, either the order data or the other parameters sent during the action call. Values in action_data, order |
depends_on.key_path.path | String | Defines the field with which the action data will be compared. The path can also be a subfield e.g. "order_meta.delivery_type" |
depends_on.function | String | Defines the operator used for the comparison, you need to adapt value type accordingly |
depends_on.value | String, Integer, Decimal, Array | Defines the value with which the data will be compared |
Detail of depends_on functions
Operator keyword | Value types associated | Description |
---|---|---|
equals | String, Integer, Decimal, Array | Action data should be equal to value |
not_equals | String, Integer, Decimal, Array | Action data should be different from value |
in_list | Array | Action data should be in value |
not_in_list | Array | Action data should not be in value |
lower_than | Integer , Decimal | Action data should be lower than value |
lower_than_or_equals | Integer , Decimal | Action data should be lower or equal to value |
greater_than | Integer , Decimal | Action data should be greater than value |
greater_than_or_equals | Integer , Decimal | Action data should be greater or equal to value |
regex | String | Action data should respect the regular expression |
contains | String | Action data should be formed with the value characters |
Conditional argument examples for order actions
Otto example
Extract from Marketplace API about Otto marketplace ship
action.
Marketplace API response for Otto (extract) :
{
"args_description": {
...
"return_tracking_number": {
"accept_free_values": true,
"type": "string",
"depends_on": {
"operator": "allOf",
"conditions": [
{
"key_path": {
"root": "order",
"path": "order_meta.delivery_type",
},
"function": "equals",
"value": "PARCEL",
}
],
},
},
"return_carrier": {
"accept_free_values": false,
"type": "list",
"valid_values": [.........],
"depends_on": {
"operator": "allOf",
"conditions": [
{
"key_path": {
"root": "order",
"path": "order_meta.delivery_type",
},
"function": "equals",
"value": "PARCEL",
}
],
},
}
}
}
In this particular case, we can see that both return_tracking_number
and return_carrier
have specific conditions.
return_tracking_number
is a string field that accept any tracking number as input.
return_carrier
is a string field that accept only one of the provided valid_values
.
Both fields have a depends_on
attribute with a condition meaning that fields are required only for an order with PARCEL delivery type (checked via the order.order_meta.delivery_type field).
Documents
Feed Documents
Get Documents linked to your feed
The Document API allows you to list and retrieve documents stored by Lengow.
This guide will use Zalando ZFS as a use case to introduce the different endpoints.
As stated in the title, documents are linked to a feed, so you'll need a feed id to use it.
If you use an unknown feed id, your request will return the following message:
Unknown feed id
If the feed id you are using is not linked to your account, you'll get the following message:
Forbidden: Account and Feed don't match
List available document types
Each document is assigned a document type, which help to efficiently store and retrieve them.
To retrieve all document types available for your feed, do the following call:
GET https://api.lengow.io/v3.0/document/<feed_id>/list?account_id=<account_id>
curl https://api.lengow.io/v3.0/document/1234/list?account_id=1234 -X GET
Return example for the list document type API
{
"code": 200,
"document_types": [
{
"zfs-item-quantity-one-shot": {
"description": "Real-time snapshot of ZFS warehouses inventory",
"is_one_shot": true
}
},
{
"zfs-item-quantity-snapshot": {
"description": "Daily report of ZFS warehouses inventory",
"is_one_shot": false
}
}
]
}
Example Error - No Document Feature
The given feed does not feature document management
If the feed you are using does not feature any document type, you may face a HTTP 400, with the message available in the example.
The field is_one_shot
specify whether or not this document is stored. When the value is True
, it means the document
is directly streamed from the partner. We'll see later how this can change the call to retrieve a document.
Also, the next step is not to be done for document types where is_one_shot
is True, as no document are ever saved.
List available documents of a type
Now that we have our document types, we need to list the available documents and choose the one to retrieve.
The call will be as follow :
GET https://api.lengow.io/v3.0/document/<feed_id>/<document_type>/list?account_id=<account_id>
Let's see this in context:
This call:
curl https://api.lengow.io/v3.0/document/1234/zfs-item-quantity-snapshot/list?account_id=1234 -X GET
Return example for the list document API
{
"1": {
"created_at": "2021-05-04T09:03:01.883Z",
"type": "application/csv",
"status": "ready"
}
}
In the example 1
is the id of the document, you will need this to retrieve the document later.
The data retrieved enable you to choose which document you want to download, depending, for example on the date or the status.
The status
can have the following values :
- unknown
- error
- ready
In case you download a document with the error
status, you'll receive a text file containing the error message, otherwise, the API will return the document content.
In both cases, the API will return the content type in the response headers.
Download a document
Once you have identified the document you need, you will have to download it.
To do so, we will need the following endpoint:
GET https://api.lengow.io/v3.0/document/<feed_id>/<document_type>/download/<doc_id>?account_id=<account_id>
In case the document type you need to download is flagged as is_one_shot
you can use :
GET https://api.lengow.io/v3.0/document/<feed_id>/<document_type>/download?account_id=<account_id>
If you download an is_one_shot
document, the result may sometimes be a JSON response, with a 422 code and errors that were met during the process.
To keep the previous example, the request would look like this:
curl https://api.lengow.io/v3.0/document/1234/zfs-item-quantity-snapshot/download/1?account_id=1234 -X GET
For is_one_shot
documents, you can also supply additional parameters to your request:
GET https://api.lengow.io/v3.0/document/<feed_id>/<document_type>/download?account_id=<account_id>&eans=0123456789123,0987654321987
For example, in the case of ZFS one-shot inventory reports, you can supply these three parameters:
eans
: EANs delimited by a comma (max 50)from
: date in RFC 3339 format (ex: 2020-12-02T20:32:28Z)by_location
: boolean to retrieve stocks by location
Note : eans
and from
are mandatory exclusive parameters, you have to supply only one of them
You may use the Content-type
header to know how to store the data you received
Document Content
With by_location parameter
"ean","total_quantity","total_offerable_quantity","total_non_offerable_quantity","location_id","location_quantity","location_offerable_quantity","location_non_offerable_quantity"
"0123456789123","3","3","0","zalando_location_id","1","1","0"
"0123456789123","3","3","0","zalando_location_id","2","2","0"
Without by_location parameter
"ean","total_quantity","total_offerable_quantity","total_non_offerable_quantity"
"0123456789123","3","3","0"
The response headers
Date : Tue, 04 May 2021 10:08:59 GMT
Server : WSGIServer/0.2 CPython/3.6.13
Content-Type : application/csv
Content-Length : 179
X-Frame-Options : SAMEORIGIN
Document Expired error
HTTP 410.
Requested document unavailable or expired
Missing parameters for one-shot documents
HTTP 401
Missing mandatory GET parameter : <parameter_name>
Error while streaming the document
{
"code" : "422",
"errors": <errors>
}
Logistics
The Logistics API allows you to perform different actions and retrieve different resources about your stock shipments to marketplaces warehouses.
All these API need a feed id on a logistic-compatible marketplace in order to work.
Create and retrieve shipping notices
A shipping notice is the representation of a shipment to a partner's warehouse.
Example request for shipping notice creation:
curl https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/?account_id=<account_id> -X POST -H "Content-Type: application/json" --data '{"key": "value"}'
Example result for shipping notice creation:
{
"shipping_notice_id": 1,
"marketplace_shipping_notice_id": "shipping_1234",
"lengow_status": "SHIPMENT_NEW",
"marketplace_status": "shipping_notice_created",
"extra": {},
"resources": {
"tracking_status": "/feed/1/shipping_notices/1/tracking_status"
},
}
Example errors for shipping notice creation:
{
"error": "Shipping notices are not available for Amazon FR."
}
{
"error": "Error while creating shipping notice: Internal server error."
}
Create a shipping notice
To create a shipping notice, use the following:
POST https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/?account_id=<account_id>
Input data may change according to marketplace variations. Please refer to the corresponding guide.
In the response, you will retrieve a shipping notice id ("shipping_notice_id" value in the JSON response). Be sure to save it for further steps.
Example result for shipping notice retrievement:
{
"notice": {
"shipping_notice_id": 1,
"marketplace_shipping_notice_id": "shipping_1234",
"lengow_status": "SHIPMENT_NEW",
"marketplace_status": "shipping_notice_created",
"extra": {},
"resources": {
"tracking_status": "/feed/1/shipping_notices/1/tracking_status"
},
"actions": ["update_shipping_notice", "create_announced_item_set"],
}
}
Example error for shipping notice retrievement:
{
"error": "Shipping notice does not exist or does not belong to that feed."
}
Retrieve a shipping notice
After that, you can retrieve your shipping notice with:
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>?account_id=<account_id>
Example result for shipping notices listing:
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"shipping_notice_id": 1,
"marketplace_shipping_notice_id": "001",
"lengow_status": "SHIPMENT_NEW",
"marketplace_status": "shipping_notice_created",
"extra": {},
"resources": {
"tracking_status": "/feed/1/shipping_notices/1/tracking_status"
},
"actions": ["update_shipping_notice"],
},
{
"shipping_notice_id": 2,
"marketplace_shipping_notice_id": "002",
"lengow_status": "SHIPMENT_CONTENT_CONFIRMED",
"marketplace_status": "announcement_confirmed",
"extra": {},
"resources": {
"tracking_status": "/feed/1/shipping_notices/2/tracking_status"
},
"actions": ["confirm_announcement"],
},
{
"shipping_notice_id": 3,
"marketplace_shipping_notice_id": "003",
"lengow_status": "SHIPMENT_PREPARATION",
"marketplace_status": "dispatch_item_set_created",
"extra": {},
"resources": {
"tracking_status": "/feed/1/shipping_notices/3/tracking_status"
},
"actions": ["confirm_dispatch"],
},
],
}
Retrieve all shipping notices
Additionally, you can retrieve all shipping notices:
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/?account_id=<account_id>
You can also provide a lengow_status
in query params to filter shipping notices by status.
See below for a list of existing statuses.
If you want to filter on marketplace statuses, you can provide a marketplace_status
in query parameters.
Shipping notice object
Field | Type | Description |
---|---|---|
shipping_notice_id | Integer | Lengow identifier for shipping notice (unique) |
marketplace_shipping_notice_id | String | Shipping notice identifier on the marketplace |
lengow_status | Lengow status | Lengow status |
marketplace_status | String | Marketplace status |
extra | Object | Object containing special informations about shipping notice (differs according to marketplace) |
resources | Object | Link to all related resources |
actions | Array | Available actions |
List of shipping notices Lengow statuses
Status | Description |
---|---|
SHIPMENT_NEW | Shipment created |
SHIPMENT_CONTENT_ANNOUNCED | Content of shipment has been announced |
SHIPMENT_CONTENT_CONFIRMED | Content of shipment has been confirmed |
SHIPMENT_AWAITED | Shipment is awaited |
SHIPMENT_PREPARATION | Shipment in is preparation |
SHIPMENT_SHIPPED | Shipment is concluded |
Example request for an action on a shipping notice:
curl https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/dispatch-item-set?account_id=<account_id> -X POST -H "Content-Type: application/json" --data '{"key": "value"}'
Most common errors are described here.
Error: Unknown shipping notice id
{
"error": "Shipping notice does not exist or does not belong to that feed."
}
Error : Unknown action
{
"error": "Action test_action does not exist. Available actions for this shipping notice are action1, action2."
}
Error: Action forbidden for current shipping notice status
{
"error": "Action test_action is not available from status dispatch_confirmed. Available actions for this shipping notice are action1, action2."
},
Perform actions on shipping notices
Available actions and input data may depend on marketplace variations. Please refer to corresponding guide.
To issue an action on a shipping notice, you must use:
POST https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/<action_name>?account_id=<account_id>
Retrieve resources related to shipping notices
According to marketplace variations, additionnal resources can be associated to shipping notices. Available resources names can be found by retrieving a shipping notice. Response format depends on the marketplace and endpoint.
To access a shipping notice resource, you must use:
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/<resource_name>?account_id=<account_id>
Note: error responses use the same format as the action API
Retrieve stock movements informations
Example response for resources listing:
{
"received_items": {"required": ["from", "to"]},
"liquidated_items": {
"required": ["from", "to"],
"optional": ["purchase_order_number"],
},
}
Example request for stock movement retrievement:
curl --location --request GET 'https://api.lengow.io/v3.0/logistics/feed/1/stock_movements/liquidated_items?account_id=1&from=2020-02-21T07:30:00Z&to=2020-02-22T07:30:00Z'
In addition to resources associated to shipping notices, you can retrieve global resources about your stock movements.
First, you can use the stock movements base endpoint to retrieve the list of available resources and associated request parameters.
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/stock_movements/?account_id=<account_id>
Next, you can request any resources returned at last step with their parameters:
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/stock_movements/<resource>?account_id=<account_id>
Response data may vary according to marketplace and resource.
Zalando Fulfillment Solutions
This documentation will guide you to use Lengow Logistics API with Zalando Fulfillment Services.
The informations that Lengow Logistics API will return come from Zalando API, so they may evolve faster than our documentation. Please do not hesitate to reach us if you see incoherences between our API documentation and answers you are retrieving.
In the following endpoints, you will need to specify a feed_id. This feed_id allows Lengow to retrieve your Zalando credentials. If you have several Zalando feeds on Lengow you can use any feed_id you want.
Shipping notice creation
Input data for shipping notice creation
{
"carrier_name": "DHL",
"requested_zalando_location_id": "29809185-6a98-4691-a15b-e8d16839b6e8",
"pallets_count": 0,
"colli_count": 0,
"hanging_goods_count": 0,
"earliest_delivery_date": "2017-07-21",
"merchant_b2b_reference": "sn123",
"comments": "This is a shipping notice.",
"contact_email": "test@zfs.com",
}
The first thing you need to do in order to ship products to Zalando warehouses, is to create a shipping notice :
POST https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/?account_id=<account_id>
All parameters are optional.
Parameters for shipping notice creation
Parameter | Required | Type | Description |
---|---|---|---|
carrier_name | False | String | carrier name (max length: 100) |
requested_zalando_location_id | False | String | Zalando warehouse location id |
pallets_count | False | Integer | Pallets count |
colli_count | False | Integer | Colli count |
hanging_goods_count | False | Integer | Hanging goods count |
earliest_delivery_date | False | Date | Earliest date for delivery |
merchant_b2b_reference | False | String | Your identifier for this shipping notice |
comments | False | String | Comments about the shipping notice |
contact_email | False | String | Your contact email address |
Response example for shipping notice creation
{
"shipping_notice_id": 12345,
"marketplace_shipping_notice_id": "shipping_1234",
"lengow_status": "SHIPMENT_NEW",
"marketplace_status": "initial",
"extra": {},
"resources": {},
"actions": [
"update_shipping_notice", "create_announced_item_set"
]
}
In return, if everything goes as planned, you should receive something like this :
At this stage, the marketplace_status of your shipping notice is initial
and its lengow_status is SHIPMENT_NEW
.
The shipping_notice_id
parameter is referring to a Lengow internal id, whereas the marketplace_shipping_notice_id
is the id of the shipping notice within the marketplace (shipping_notice_ID
in Zalando API here)
The actions
parameter lists all possible future actions for this shipping notice.
Shipping notices listing
Example result for shipping notice retrievement:
{
"shipping_notice_id": 12345,
"marketplace_shipping_notice_id": "shipping_1234",
"lengow_status": "SHIPMENT_SHIPPED",
"marketplace_status": "ready_to_receive",
"extra": {
"merchant_b2b_reference": "789",
"delivery_date": "2021-10-11",
},
"resources": {
"tracking_status": "/feed/1/shipping_notices/12345/tracking_status",
"announced_item_sets": "/feed/1/shipping_notices/12345/announced_item_sets",
"dispatch_item_sets": "/feed/1/shipping_notices/12345/dispatch_item_sets",
},
"actions": ["confirm_dispatch"]
}
During the whole process, you can retrieve your shipping notice using
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>?account_id=<account_id>
.
The URL you retrieve in the following fields allows you to realize a new request to get the details (see explanations in further steps) :
- announced_item_set
- dispatch_item_set
- tracking_status
Example result for shipping notices listing:
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"shipping_notice_id": 1,
"marketplace_shipping_notice_id": "001",
"lengow_status": "SHIPMENT_NEW",
"marketplace_status": "initial",
"extra": {
"merchant_b2b_reference": "789",
"delivery_date": "2021-10-11",
},
"resources": {},
"actions": ["update_shipping_notice"],
},
{
"shipping_notice_id": 3,
"marketplace_shipping_notice_id": "003",
"lengow_status": "SHIPMENT_SHIPPED",
"marketplace_status": "ready_to_receive",
"extra": {
"merchant_b2b_reference": "123456",
"delivery_date": "2021-07-21",
},
"resources": {
"tracking_status": "/feed/1/shipping_notices/3/tracking_status",
"announced_item_set": "/feed/1/shipping_notices/3/announced_item_set",
"dispatch_item_set": "/feed/1/shipping_notices/3/dispatch_item_set",
},
"actions": ["confirm_dispatch"],
},
],
}
To retrieve all shipping notices you created on ZFS you can use :
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices?account_id=<account_id>
Parameters for shipping notice listing
Parameter | Required | Type | Description |
---|---|---|---|
lengow_status | False | String | Lengow status |
marketplace_status | False | String | Marketplace status (Zalando) |
Example to retrieve all shipping notices with the lengow_status delivery_date_confirmed :
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices?account_id=<account_id>&status=delivery_date_confirmed
Shipping notice update
Input data for shipping notice creation
{
"carrier_name": "DHL",
"requested_zalando_location_id": "29809185-6a98-4691-a15b-e8d16839b6e8",
"pallets_count": 0,
"colli_count": 0,
"hanging_goods_count": 0,
"earliest_delivery_date": "2017-07-21",
"merchant_b2b_reference": "sn123",
"comments": "This is a shipping notice.",
"contact_email": "test@zfs.com",
}
After the shipping notice creation, you may update shipping notices using update_shipping_notice action. To do so, use the same parameters you used for creation :
POST https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/update_shipping_notice?account_id=<account_id>
The answer will be the same you received for creation.
Announced item set creation
Example input for announced item set creation:
{
"items": [{
"ean": "0191476239145",
"quantity": 100
}, {
"ean": "9663480597111",
"quantity": 10,
}]
}
The action create_announced_item_set needs a list of EANs and quantities.
POST https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/create_announced_item_set?account_id=<account_id>
Parameters for announced item set creation
Parameter | Required | Type | Description |
---|---|---|---|
items | True | List | Items object |
items.ean | True | String | EAN of the item |
items.quantity | True | Integer | Amount of items to be shipped |
Example response for announced item set creation:
{
"notice": {
"shipping_notice_id": 12345,
"marketplace_shipping_notice_id": "shipping_1234",
"lengow_status": "SHIPMENT_CONTENT_ANNOUNCED",
"marketplace_status": "initial_announced",
"extra": {},
"resources": {
"announced_item_sets": "/feed/1/shipping_notices/12345/announced_item_sets",
},
"actions": [
"update_announced_item_set", "confirm_announcement"
]
}
}
In return, if everything goes as planned, you should receive this type of answer :
The marketplace_status of your shipping notice will be initial_announced
and its lengow_status will become SHIPMENT_CONTENT_ANNOUNCED
.
The actions
parameter lists all possible future actions for this shipping notice.
Announced item set listing
At any moment, you can retrieve the announced item set of one particular shipping notice in real time using :
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/announced_item_sets?account_id=<account_id>
Example response for announced item set retrievement:
{
"data": [
{
"items": [
{
"ean": "0191476239145",
"quantity": 0,
"sku": "TH341G023-K1100XL000",
"validation_state": "string"
}
],
"items_total": 0,
"items_valid": 0,
"validation_state": "string",
"validation_description": "string"
}
],
}
Announced item set update
Example input for announced item set update:
{
"items": [{
"ean": "0191476239145",
"quantity": 100
}, {
"ean": "9663480597111",
"quantity": 10,
}]
}
After the announced item set creation, you may update them using update_announced_item_set action. To do so, use the same parameters you used for creation :
POST https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/update_announced_item_set?account_id=<account_id>
Announcement confirmation
Example response for announced item set confirmation:
{
"notice": {
"shipping_notice_id": 12345,
"marketplace_shipping_notice_id": "shipping_1234",
"lengow_status": "SHIPMENT_CONTENT_CONFIRMED",
"marketplace_status": "ready_for_delivery_date",
"extra": {},
"resources": {
"announced_item_sets": "/feed/1/shipping_notices/12345/announced_item_sets",
},
"actions": []
}
}
You can confirm the announcement using confirm_announcement action :
POST https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/confirm_announcement?account_id=<account_id>
This action does not need any input.
In return, if everything goes as planned, you should receive something like this :
The marketplace_status of your shipping notice will become ready_for_delivery_date
and its lengow_status will become SHIPMENT_CONTENT_CONFIRMED
.
Dispatch item set creation
Example input for dispatch item set creation:
{
"items": [{
"ean": "0191476239145",
"quantity": 100
}, {
"ean": "9663480597111",
"quantity": 10,
}]
}
To realize this action, you will first need to make sure your shipping notice lengow_status changed to SHIPMENT_AWAITED
, which means Zalando added a confirmed_delivery_date to your shipping notice.
You can see this confirmed_delivery_date in the extra object of the shipping notice (Shipping notice listing answer).
You need to create a dispatch item set through create_dispatch_item_set action.
This is the same input as create_announced_item_set, update_announced_item_set or update_dispatch_item_set:
POST https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/create_dispatch_item_set?account_id=<account_id>
Example response for dispatch item set creation:
{
"notice": {
"shipping_notice_id": 12345,
"marketplace_shipping_notice_id": "shipping_1234",
"lengow_status": "SHIPMENT_PREPARATION",
"marketplace_status": "ready_for_dispatch",
"extra": {},
"resources": {
"announced_item_sets": "/feed/1/shipping_notices/12345/announced_item_sets",
"dispatch_item_sets": "/feed/1/shipping_notices/12345/dispatch_item_sets",
},
"actions": [
"confirm_dispatch",
]
}
}
In return, if everything goes as planned, you should receive something like this :
The marketplace_status of your shipping notice will become ready_for_dispatch
and its lengow_status will become SHIPMENT_PREPARATION
.
Dispatch item set update
Example input for dispatch item set update:
{
"items": [{
"ean": "0191476239145",
"quantity": 100
}, {
"ean": "9663480597111",
"quantity": 10,
}]
}
After creation, you can update you dispatch item set with update_dispatch_item_set action.
The answer is the same it was for creation.
Dispatch item set listing
Example response for dispatch item set retrievement:
{
"data": [
{
"items": [
{
"ean": "0191476239145",
"quantity": 0,
"sku": "TH341G023-K1100XL000",
"validation_state": "string"
}
],
"items_total": 0,
"items_valid": 0,
"validation_state": "string",
"validation_description": "string",
"created": "2017-07-21T17:32:28.123Z"
}
],
}
As announced item sets, you can also retrieve your current dispatch item sets in real time:
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/dispatch_item_sets?account_id=<account_id>
Dispatch item set confirmation
Example response for dispatch item set confirmation:
{
"notice": {
"id": 12345,
"marketplace_shipping_notice_id": "shipping_1234",
"lengow_status": "SHIPMENT_SHIPPED",
"marketplace_status": "ready_to_receive",
"extra": {},
"resources": {
"tracking_status": "/feed/1/shipping_notices/12345/tracking_status",
"announced_item_sets": "/feed/1/shipping_notices/12345/announced_item_sets",
"dispatch_item_sets": "/feed/1/shipping_notices/12345/dispatch_item_sets",
},
"actions": []
}
}
The final step through API is to confirm your dispatch item using confirm_dispatch action. Like confirm_announcement, this does not need any input data
POST https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/confirm_dispatch?account_id=<account_id>
In return, if everything goes as planned, you should receive something like this :
The marketplace_status of your shipping notice will become ready_to_receive
and its lengow_status will become SHIPMENT_SHIPPED
.
Once the items are received in the Zalando warehouses, the marketplace_status will become closed
(lengow_status doesn't change).
Shipment tracking
{
"data": [
{
"zalando_advice_id": "99200000",
"shipping_notice_id": "a2e9e478-f9ec-4af3-b773-75da5b6d7470",
"tour_number": "20171026-0001-BR-ERF",
"to_location": "string",
"from_location": "string",
"planned_arrival_time_at_dock": "2021-10-05T13:11:44.362Z",
"planned_arrival_time_at_yard": "2021-10-05T13:11:44.362Z",
"planned_amount_of_loading_units": {
"pallets": 0,
"colli": 0,
"hanging_garments": 0
},
"actual_amount_of_loading_units": {
"pallets": 0,
"colli": 0,
"hanging_garments": 0
},
"type": "ZFS_NEW_GOODS",
"current_status": {
"status_text": "unloading",
"status_details": "Tour get rejected because ....",
"last_updated": "2021-10-05T13:11:44.362Z"
}
}
]
}
After shipping, you can track your shipment in real time.
This corresponds to the Zalando Tours API.
To create a request, use the shipping notice id :
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/shipping_notices/<shipping_notice_id>/tracking_status?account_id=<account_id>
Possible status of a tour :
- shipped
- arrived
- unloading
- unloaded
Retrieve stock movements
With Logistics API, you can retrieve stock movements with:
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/stock_movements/<resource>?account_id=<account_id>
Resource depends on marketplace and for Zalando / ZFS, there is currently four available resources:
- received_items: which corresponds to Inbound receive process (your goods shipped to Zalando)
- returned_items: which corresponds to Outbound return process (goods Zalando returns to you at your request)
- intra_community_movements: which corresponds to Intra Community Movements (ICM) (Cross Border Movements data of ZFS products, used for Intrastat declarations)
- liquidated_items: which corresponds to Liquidation Data (your goods liquidated to Zalando offprice channel on your request)
The retention time for data in ZFS service is 100 days. After that, data may be deleted without notice.
Response example for stock movements resources listing
{
"received_items": {"required": ["from", "to"]},
"liquidated_items": {
"required": ["from", "to"],
"optional": ["purchase_order_number"],
},
}
For each resource, there is the required and optional parameters to use as query parameters during your request. For example :
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/stock_movements/liquidated_items?account_id=1&from=2020-02-21T07:30:00Z&to=2020-02-22T07:30:00Z
To retrieve the current available resources, you can use :
GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/stock_movements/?account_id=<account_id>
Received items
Example response for received items
{
"data": [
{
"zalando_advice_id": 99200001,
"merchant_b2b_reference": "reference",
"ean": "0191476239145",
"parent": {
"id": "string"
},
"quality_label": "00014D02W8V",
"location_id": "29809185-6a98-4691-a15b-e8d16839b6e8",
"received_timestamp": "2017-07-21T17:32:28Z",
"consumed_timestamp": "2017-07-21T17:32:28Z",
"tour_number": "20181031-0015-SWI1-EF"
}
]
}
Use GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/stock_movements/received_items?account_id=1
Returned items
Example response for returned items
{
"data": [
{
"merchant_b2b_reference": "reference",
"ean": "0191476239145",
"quality_label": "00014D02W8V",
"location_id": "29809185-6a98-4691-a15b-e8d16839b6e8",
"shipped_timestamp": "2017-07-21T17:32:28Z",
"consumed_timestamp": "2017-07-21T17:32:28Z",
"zalando_shipment_number": "1234567890123456",
"destination": {
"city": "string",
"country_code": "string",
"first_name": "string",
"last_name": "string",
"salutation": "string",
"street": "string",
"zip": "string"
},
"quality_category": "A",
"defect_levels": {
"level_1": "optional defect description",
"level_2": "optional defect description"
}
}
]
}
Use GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/stock_movements/returned_items?account_id=1
Intra community movements
Example response for intra community movements
{
"data": [
{
"report_date": "2020-04-01",
"movements": [
{
"product_sku": "AAA22O08A-A1100AS000",
"ean": "2001231121234",
"quantity": 1,
"destination_stock_location": {
"location_id": "b1aa94aa-104a-457a-a17a-a52aaa88aa3a",
"name": "Gardno",
"country_code": "PL"
},
"source_stock_location": {
"location_id": "32aaa430-a835-44aa-947a-4a1aaaa1a615",
"name": "Erfurt",
"country_code": "DE"
},
"order_number": "20200401-erfurt-gardno",
"movement_type": "customer_order_relocation"
}
]
}
]
}
Use GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/stock_movements/intra_community_movements?account_id=1
Liquidated items
Example response for liquidated items
{
"data": [
{
"merchant_id": "899561ce-e76e-11ea-b770-5ff9afbbecdd",
"purchase_order_number": "PO123",
"shipping_notice_number": "cd0424c2-e76e-11ea-b8d9-df7a5c43dac0",
"ean": "0191476239145",
"sku_simple": "TH341G023-K1100XL000",
"quantity": "40",
"stock_location_id": "fd10a17c-e76e-11ea-935d-53ca727cc5e7",
"liquidation_date": "2020-02-19",
"reporting_date": "2020-02-25"
}
]
}
Use GET https://api.lengow.io/v3.0/logistics/feed/<feed_id>/stock_movements/liquidated_items?account_id=1
Preprocessing
This API allows to create a preprocessing task.
Parameters
Two mandatory parameters: account_id and catalog_id. If there is a preprocessing for several catalogs, you need just input one catalog id, then it will launch one proprecessing task for all related catalogs.
curl https://api.lengow.io/v3.0/preprocessing/job/?account_id=1&catalog=1 --header "Authorization: 6b7280eb-e7d4-4b94-a829-7b3853a20126"
Parameter | Type | Required |
---|---|---|
account_id | Integer | Yes |
catalog_id | Integer | Yes |