API Release Notes
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
- Marketplaces API: new entry
features
- Category of change: Non breaking new feature
- Impacted: Marketplaces API
- Release date: 2024-10
- Description:
- The new property
features
on the marketplace object indicates if a marketplace offers special features, like Invoice Upload for instance.
- The new property
Released
Orders: new filter
lengow_line_status
- Category of change: Non breaking new feature
- Impacted: Orders API
- Release date: 2024-06
- Description:
- The new filter
lengow_line_status
allows to search for order with lines (cart items) with specific status(es).
- The new filter
Marketplaces reports: new endoint to download reports
- Category of change: New feature
- Release date: 2024-05
- Description:
- the report/export endpoint offers to download product integration reports as CSV.
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
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.
Getting started
Welcome to Lengow API documentation.
Lengow API is a REST-based API that allows you to:
- List and retrieve the orders of your account
- Execute actions on orders: acceptance, shipment, cancellation, and refund
- Display the complete list of possible order actions authorized by each marketplace, at which status and with which mandatory or optional parameters
- Retrieve invoice documents
- Communicate with Zalando warehouse
Technical Aspect
- The API respects the
REST
fundamentals. - The base URL for the latest version is
api.lengow.io/v3.0
overHTTPS
. - All data is sent and received as
JSON
by default.
URL
Production URL: https://api.lengow.io
Specific types
types | Description |
---|---|
Country | Depending on resources, countries are specified as two (ISO 3166-2) or three characters ISO 3166-1 alpha-3 |
Date | All date/time values are specified in ISO 8601 ex: 2020-03-16T04:46:00+00:00 |
Currency | All currencies are specified as three characters (ISO 4217) |
Money | decimal or string |
Authentication
You need to authenticate yourself before making any request on the Lengow API.
[POST] Get a token
Method | Endpoint | Description |
---|---|---|
POST | https://api.lengow.io/access/get_token |
This endpoint allows you to authenticate yourself. Use this resource to get the credentials you need to start using our API. |
To get your token you will need 2 API keys: secret and access_token. You can find them on the API section of your Lengow account
You can generate a new secret and access_token on the API section of your Lengow account. The previously generated tokens will be automatically revoked.
API keys are unique to your account. If you are using a subaccount you will have different API keys per subaccount.
The session token returned by access/get_token is valid for one hour. It is unnecessary to request a token before each request. To check the remaining validity time of a token, you can use the /me API.
curl "https://api.lengow.io/access/get_token" -X POST --data "access_token=${ACCESS_TOKEN}&secret=${SECRET}"
{"token": "${TOKEN}", "account_id": 1}
Request Body Schema
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 -H "Authorization: ${TOKEN}"
Once you have a token, all your API request will need a Authorization
header.
Orders
Getting started with orders
Method | Endpoint | Description |
---|---|---|
GET, POST, PATCH | https://api.lengow.io/v3.0/orders/ |
This endpoint allows you to retrieve and list your account orders (including the details of the order), mark the order with your internal order ID, perform actions on orders and check if they succeed. Each endpoint is detailed below. |
List of order statuses
From a Marketplace point of view, they all have their order statuses.
In Lengow, we regroup and standardize all these statuses in the lengow_status
.
If you wish to filter based on the order status when retrieving orders, we advise you to rely on the lengow_status
parameter.
Status | Allowed action | Description |
---|---|---|
new | None | Order was created but no action is available for now. |
waiting_acceptance | accept, refuse | The merchant has to accept or refuse the order. Automatic acceptance tool available on your Lengow account. |
refused | None | The order was refused by the merchant. |
accepted | None | The order has been accepted by the merchant and waiting for the marketplace authorization for shipping. |
waiting_shipment | ship, cancel, refund | Depending on the marketplace the merchant can ship, cancel or refund the order. |
shipped | refund | The order is waiting for the final marketplace validation for closing. Depending on the marketplace the merchant can refund the order. |
closed | None | The order is closed, no more actions are available. |
canceled | refund | The order was canceled. Depending on the marketplace, the order can be refunded. |
refunding | None | The refund demand is waiting for 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 pickup. Specific to eBay |
to_pickup | None | The order is ready for pickup. Specific to eBay |
pickup_completed | None | The order has been picked up by the buyer. Specific to eBay |
pickup_canceled | None | The pickup has been cancelled. Specific to eBay |
to_refund | refund | The merchant has to refund the order. |
Order Workflow
The Order retrieval and update process usually flows like this with Lengow REST API:
- Order is placed on a marketplace
- Order is retrieved from the marketplace by Lengow every 15 minutes
- Merchants will retrieve orders that haven't already been imported into their system. Refers to get orders endpoint and the main filter to retrieve the order.
- Once those orders have been imported into their system successfully, the merchant can mark them by setting the merchant order ID. Refers to set merchant order ID endpoint.
- Then Orders may be updated with 5 actions: Accept, Refuse, Ship, Cancel and Refund. Refers to create an action on an order endpoint. Acceptation may be automated by activating automatic order acceptance on your Lengow account. To know which action is available by marketplace and which parameters are required for each action, refer to get marketplace informations endpoint.
- Merchant can list all the actions on the orders and verify if they have been processed by the marketplace. Refers to List all actions on orders endpoint
The diagram below provides a simplified representation of the Lengow order workflow. It does not consider the specificities of each marketplace. It would be best to analyse the statuses and possible actions for each of your marketplaces individually. get marketplace informations endpoint
[GET] List and retrieve orders
Simple call:
curl "https://api.lengow.io/v3.0/orders/?account_id=1"
With pagination:
curl "https://api.lengow.io/v3.0/orders/?account_id=1&page=5&page_size=50"
With ordering:
curl "https://api.lengow.io/v3.0/orders/?account_id=1&ordering=marketplace,-updated_at"
With filtering:
curl "https://api.lengow.io/v3.0/orders/?account_id=1&marketplace=menlook"
Method | Endpoint | Description |
---|---|---|
GET | https://api.lengow.io/v3.0/orders/ |
This endpoint allows you to retrieve a list of orders with filters, including order details |
Order data differs from one marketplace to the next, as a result, some properties may be populated, while others are null or blank.
Pagination - The result is paginated (limited to a maximum of 100 orders by page). Different parameters can be provided to manage this pagination: page and page_size.
Ordering - You can control the ordering of results with the ordering parameter.
Filtering - You can use different filters that can narrow down the selection of orders in the response:
To get all the existing orders for a specific channel, use the marketplace
query parameter
To get an order with the order reference of the channel, use the marketplace_order_id
query parameter
To get orders on a specific status, use the lengow_status
or lengow_line_status
query parameters
To get orders according to a period, use the order date: marketplace_order_date_from
, marketplace_order_date_to
query parameter
Query Parameters
Parameter | Type | Default | Description |
---|---|---|---|
page | Integer | 1 | The page number |
page_size | String | 100 | Number of results by page. Max 100 |
ordering | String or Date | marketplace -marketplace_order_date -imported_at |
Enum: marketplace marketplace_order_id merchant_order_id lengow_status marketplace_status marketplace_order_date imported_at updated_at Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'. |
set_currency | String | your account's currency | The value must be specified as three characters (ISO 4217) |
account_id | Integer | filter by account | |
marketplace | String | filter by Marketplace code | |
marketplace_order_id | Integer | filter by marketplace identifier of the order | |
merchant_order_id | String or None |
filter by merchant identifier of the order | |
lengow_status | String | filter by lengow_status | |
lengow_line_status | String | filter by the status of the order line | |
marketplace_status | String | filter by marketplace status | |
marketplace_order_date_from | Date | filter by marketplace order creation date from | |
marketplace_order_date_to | Date | filter by marketplace order creation date to | |
imported_from | Date | filter by imported by Lengow from | |
imported_to | Date | filter by imported by Lengow to | |
updated_from | Date | filter by updated by from | |
updated_to | Date | filter by updated by to |
If you want to change the currency, you can use the set_currency
parameter. The value must be specified as three characters (ISO 4217).
Note on filters:
- By default, the
marketplace_order_date_from
filter is set totoday - 7 days
. - 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.
Response Schema application/json
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 sub-objects
The order object contains sub-objects, they are all defined underneath
Specific order type reference | Description |
---|---|
Order | The base Order object |
Package | Informations about the package, its delivery and the 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 |
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 as lengow_status. |
total_order | Decimal | Order price (shipping price and taxes included) |
total_tax | Decimal | Order tax |
commission | Decimal | Marketplace commission (appears in Lengow status "waiting_acceptance" or "shipped" in the function of marketplace workflow) |
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 orders older than 6 months. |
Package object
A package groups all lines 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 example. = 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 |
[PATCH] 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"
}'
Method | Endpoint | Description |
---|---|---|
PATCH | https://api.lengow.io/v3.0/orders/moi/ |
This endpoint allows you to set merchant internal order id in Lengow. The internal order ID of your platform e-commerce |
When merchant retrieves the order in their system for the first time they can set their internal order id. The goal is to retrieve only orders that haven't already been marked with the merchant order ID by using the filter merchant_order_id is not null. This is a good way to ensure order imports are not duplicated.
Request Body Schema application/json
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, an order object is returned
[GET] List all actions on orders
Simple call:
curl "https://api.lengow.io/v3.0/orders/actions/?account_id=1"
Method | Endpoint | Description |
---|---|---|
GET | https://api.lengow.io/v3.0/orders/actions/ |
This endpoint allow you to check if the order status is updated, and if the action has been sent with success, if not the error message associated |
Query Parameters
With filtering:
curl "https://api.lengow.io/v3.0/orders/actions/?account_id=1&marketplace_order_id=123456-ABC&marketplace=darty"
Parameter | Required | Type | Description |
---|---|---|---|
id | False | String | An order id |
account_id | True | Integer | Account ID |
marketplace | False | String | Marketplace code |
marketplace_order_id | False | String | Marketplace identifier of the order |
action_type | False | String | Action types |
processed | False | Boolean | Is the action processed by the marketplace? |
queued | False | Boolean | Is Lengow still trying to process this action on the marketplace? |
tracking_number | False | String | Tracking number |
carrier | False | String | Carrier |
line | False | String | marketplace_order_line_id |
created_from | False | Date | Created date in UTC |
created_to | False | Date | Created date in UTC |
updated_from | False | Date | Updated date in UTC |
updated_to | False | Date | Updated date in UTC |
errors | False | String | Returned error message |
Response Schema application/json
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 | True when the action has been successfully handled by the Marketplace. False when the action has failed. |
queued | Boolean | True when the action is waiting for processing (or retrying on failure). False when the action has been processed |
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 message. To have the final error, you should wait that queued become false. |
Example: How to check order action failed, with filters "marketplace", "processed" and "queue"
curl --'https://api.lengow.io/v3.0/orders/actions/?account_id=1&marketplace=veepee_pink_fr&processed=False&queued=False'
--header 'Authorization: 41db47ab-4a83-487e-a0c3-cb27e92742d2'
{
"count": 16778,
"next": "https://api.lengow.io/api/v3.0/orders/actions/?account_id=1&marketplace=veepee_pink_fr&page=2&processed=false&queued=false",
"previous": null,
"results": [
{
"id": 81428159,
"marketplace_order_id": "221211V1101346333",
"account_id": 223,
"marketplace": "veepee_pink_fr",
"action_type": "ship",
"processed": false,
"queued": false,
[...]
"errors": "Tracking number is empty",
[...]
The order action "ship" has been treated by the marketplace veepee "queued = false", but has been refused "processed: false" because of the "errors: tracking number is empty"
How to track failed and successful action
You can track the status of each action with "queued" and "processed" filters.
- successful action: queued = false and processed = true
failed action: queued = false and processed = false
"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, and false when the action has failed. When "processed" is “false” an error message will indicate the reason for the failure. Check the value filled in the field “errors” to fix the issue and resend the order action.
[POST] 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"
}
Method | Endpoint | Description |
---|---|---|
POST | https://api.lengow.io/v3.0/orders/actions/ |
This endpoint allow you to create an action on a given order |
Available action types
Available actions depend on the marketplace. Please refer you to the marketplace API.
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 the order's delivery date (currently only available for El Corte Ingles) |
set_eligible_shipping_methods | Retrieve eligible shipping methods for the 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) |
Mandatory or conditional query parameters for order actions
Depending on the marketplace and action, some parameters are mandatory or conditional and need to be included or to have specific values. Please refer to marketplace API.
Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
marketplace_order_id | True | String | Order identifier of the marketplace |
account_id | True | Integer | Account ID |
marketplace | True | String | Marketplace code |
action_type | True | String | Action types |
tracking_number | Conditional | String | Tracking number |
tracking_url | Conditional | String | Tracking URL |
carrier | Conditional | String | Carrier |
line | Conditional | String | marketplace_order_line_id for partial action |
Order actions in asynchronous mode
These actions will be sent asynchronously to the marketplaces.
In case of failure, the action will be retried 5 times spaced 1 minute apart.
Please know that as the operations on orders are performed asynchronously, the status of an order on which an operation has been performed will not change immediately.
The status resulting from a successful operation will only appear once the marketplace has confirmed the operation's success.
We advise you to check the result of each order action before proceeding to a new one. To ensure the operation is successful, use the endpoint list all actions on orders.
If you perform an operation which has already been performed (in which case, the operation is irrelevant), you will not receive an error and the operation will be ignored by the marketplace.
The response to the API call returns the task identifier, which can then be used to obtain the status and result of the task.
Marketplaces
[GET] Get marketplace informations
Simple call :
curl https://api.lengow.io/v3.0/marketplaces/
With filtering :
curl https://api.lengow.io/v3.0/marketplaces/?account_id=1
curl https://api.lengow.io/v3.0/marketplaces/?marketplace=leroymerlin
curl https://api.lengow.io/v3.0/marketplaces/?marketplace=leroymerlin&account_id=1
Result json :
{
"leroymerlin": {
"logo": null,
"name": "Leroy Merlin",
"orders": {
"status": {
"new": [
"STAGING"
],
"closed": [
"RECEIVED",
"CLOSED"
],
"refused": [
"REFUSED"
],
"shipped": [
"SHIPPED"
],
...
},
"actions": {
"ship": {
"args": [
"tracking_number"
],
"status": [
"waiting_shipment"
],
"optional_args": [
"carrier",
"carrier_name",
"tracking_url"
],
"args_description": {
"carrier": {
"type": "list",
"depends_on": null,
"valid_values": {
"BRT": {
"label": "IT_BRT Italia"
},
"DHL": {
"label": "FR_DHL"
},
...
},
"default_value": null,
"accept_free_values": false
},
"carrier_name": {
"type": "string",
"depends_on": null,
"valid_values": {},
"default_value": null,
"accept_free_values": true
},
"tracking_url": {
"type": "string",
"depends_on": null,
"valid_values": {},
"default_value": null,
"accept_free_values": true
},
"tracking_number": {
"type": "string",
"depends_on": null,
"valid_values": {},
"default_value": null,
"accept_free_values": true
}
}
},
"accept": {
"args": [],
"status": [
"waiting_acceptance"
],
"optional_args": [
"line"
],
"args_description": {
"line": {
"type": "line_number",
"depends_on": null,
"valid_values": {},
"default_value": null,
"accept_free_values": true
}
}
},
"refund": {
"args": [
"refund_reason"
],
"status": [
"shipped",
"closed"
],
"optional_args": [
"currency_iso_code",
"line",
"refund_shipping",
"refund_shipping_taxes",
"refund_taxes"
],
"args_description": {
"line": {
"type": "line_number",
"depends_on": null,
"valid_values": {},
"default_value": null,
"accept_free_values": true
},
"refund_taxes": {
"type": "boolean",
"depends_on": null,
"valid_values": {},
"default_value": "true",
"accept_free_values": false
},
"refund_reason": {
"type": "list",
"depends_on": null,
"valid_values": {
"15": {
"label": "Out of stock"
},
"16": {
"label": "Cancelled by the client prior to shipping"
},
...
},
"default_value": "",
"accept_free_values": false
},
"refund_shipping": {
"type": "boolean",
"depends_on": null,
"valid_values": {},
"default_value": "true",
"accept_free_values": false
},
"currency_iso_code": {
"type": "list",
"depends_on": null,
"valid_values": {
"ARS": {
"label": "ARS"
},
"AUD": {
"label": "AUD"
},
...
},
"default_value": "EUR",
"accept_free_values": true
},
"refund_shipping_taxes": {
"type": "boolean",
"depends_on": null,
"valid_values": {},
"default_value": "true",
"accept_free_values": false
}
}
},
"refuse": {
"args": [],
"status": [
"waiting_acceptance"
],
"optional_args": [
"line"
],
"args_description": {
"line": {
"type": "line_number",
"depends_on": null,
"valid_values": {},
"default_value": null,
"accept_free_values": true
}
}
}
},
"carriers": {
"BRT": {
"label": "IT_BRT Italia",
"lengow_code": null
},
"DHL": {
"label": "FR_DHL",
"lengow_code": null
},
...
},
"shipping_methods": {
"Home Delivery - Express": {
"label": "Home Delivery - Express",
"lengow_code": null
},
"Home Delivery - Standard": {
"label": "Home Delivery - Standard",
"lengow_code": null
},
...
}
},
"country": "FRA",
"package": "mp_leroymerlin",
"homepage": null,
"description": null,
"legacy_code": "leroymerlin",
"country_iso_a2": "FR",
"features": ["invoice_upload"]
}
}
Method | Endpoint | Description |
---|---|---|
GET | https://api.lengow.io/v3.0/marketplaces/ |
Display the complete list of possible actions authorized by each marketplace at which status and with which mandatory or optional parameters. It also gives access to the list of authorized carriers and shipping methods by marketplace. |
Marketplace code
All keys of the result are a Marketplace code
used by other APIs.
You can always refer to this API to get this code.
A Marketplace code
is unique and must match this regexp : [a-Z0-9-_]
Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
account_id | False | String | To filter your marketplaces |
marketplace | False | String | To get only the specified marketplace information using the Marketplace code name |
Response Schema application/json
Field | Type | Description |
---|---|---|
Marketplace code | Object | details of marketplace information for each Marketplace code |
Parts of marketplace information
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) |
features | Object | special features. E.g. {"invoice_upload": true} |
orders.status | Object | Mapping between Lengow's status (keys) and marketplace's status (values) |
orders.carriers | Object | All carriers available |
orders.actions | Object | Information about each action (based on Lengow's actions) |
Detail of orders.actions part
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 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 the 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 case, we can see that both return_tracking_number
and return_carrier
have specific conditions.
return_tracking_number
is a string field that accepts 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).
Amazon MSS
This endpoint will be available only if you are eligible for the Amazon Seller Fulfilled Prime program.
Please refer to Amazon documentation for further information on how to apply.
Retrieve eligible shipment data
Simple call :
POST http://api.lengow.io/v3.0/orders/actions/
This API allows you to retrieve shipment that comply with the shipment you want to send.
It will return the shipping_service_offer_id
and shipping_service_id
necessary to determine which shipment label we are going to buy and retrieve. The information are to be stored in the meta-data of the order, or the order line if you fill in the line parameter during the call.
curl http://api.lengow.io/v3.0/orders/actions/ -X POST -H "Content-Type: application/json" --data
{
"marketplace_order_id": "123-ABCD123-EFGH456",
"account_id": 1,
"marketplace": "amazon_fr",
"action_type": "set_eligible_shipping_methods",
"carrier_pickup": "",
"delivery_date": "",
"delivery_experience": "",
"from_address_city": "",
"from_address_country_code": "",
"from_address_line": "",
"from_address_mail": "",
"from_address_name": "",
"from_address_phone": "",
"from_address_postal_code": "",
"package_dimension_height": "",
"package_dimension_length": "",
"package_dimension_unit": "",
"package_dimension_width": "",
"shipping_date": "",
"weight": "",
"weight_unit": "",
"from_address_state_province": "",
"line": ""
}
Definition of request fields:
Field | Type | Description | Use |
---|---|---|---|
marketplace_order_id | String | Amazon Order ID (3-7-7 format) | required |
account_id | Integer | Your account ID on Lengow | required |
marketplace | String | Amazon Site the order is linked to | required |
action_type | String | The action you want to make (always set_eligible_shipping_methods for this action) | required |
carrier_pickup | String | Will the carrier pick up the shipment from your warehouse | required |
delivery_date | Date | The needed delivery date for your shipment | required |
delivery_experience | String | Should be one of :
|
required |
from_address_city | String | The city your warehouse is located in | required |
from_address_country_code | Country | Country Code for your warehouse | required |
from_address_line | String | First line of your warehouse address | required |
from_address_mail | String | The mail to join you | required |
from_address_name | String | The name you want to display for your warehouse | required |
from_address_phone | String | The phone number to contact your warehouse | required |
from_address_postal_code | Integer | Postal-code of your warehouse | required |
package_dimension_height | Integer | The height of the package you want to ship (must be higher than 16) | required |
package_dimension_length | Integer | The length of the package you want to ship (must be higher than 16) | required |
package_dimension_width | Integer | The width of the package you want to ship (must be higher than 16) | required |
package_dimension_unit | String | Unit for the package dimensions values. Must be one of:
|
required |
shipping_date | Date | The estimated shipping date for the order | required |
weight | Integer | The weight of the shipment | required |
weight_unit | String | The weight unit. Choose from:
|
required |
from_address_state_province | String | State or province. Required in the Canada, US, and UK marketplaces. Also required for shipments originating from China. | optional |
line | String | If you want to ship only a part of your order | optional |
Buy the shipment label
Simple call :
POST http://api.lengow.io/v3.0/orders/actions/
This API allows you to buy the selected shipment label, that will be stored with your order.
The shipment label will be available through API or using the Lengow Platform, on the order detail page.
It will return the url where you can find the document. According to the Amazon documentation, shipment label can be:
- ZPL documents ( Zebra Printing Language)
- JPEG/PNG images
- PDF documents
This action will also set you order as shipped on Amazon platform. No need to make another one.
curl http://api.lengow.io/v3.0/orders/actions/ -X POST -H "Content-Type: application/json" --data
{
"marketplace_order_id": "123-ABCD123-EFGH456",
"account_id": 1,
"marketplace": "amazon_fr",
"action_type": "set_eligible_shipping_methods",
"carrier_pickup": "",
"delivery_date": "",
"delivery_experience": "",
"from_address_city": "",
"from_address_country_code": "",
"from_address_line": "",
"from_address_mail": "",
"from_address_name": "",
"from_address_phone": "",
"from_address_postal_code": "",
"package_dimension_height": "",
"package_dimension_length": "",
"package_dimension_unit": "",
"package_dimension_width": "",
"shipping_date": "",
"weight": "",
"weight_unit": "",
"from_address_state_province": "",
"line": "",
"shipping_service_id": "",
"shipping_service_offer_id": ""
}
Definition of request fields:
For the other fields definition, you can see the previous section
Field | Type | Description | Required |
---|---|---|---|
shipping_service_id | String | The ID of the service you want to use to ship your order | True |
shipping_service_offer_id | String | The offer ID you want to submit | True |
Documents
Method | Endpoint | Description |
---|---|---|
GET | https://api.lengow.io/v3.0/document/ |
This endpoint allows you to retrieve documents such as: Invoice or delivery documents (delivery notes, return notes), ZFS stock report. It also allow you to send the VIDR to Amazon |
[GET] Invoice/Delivery Document
There is no specific query that would include all invoice documents for a particular channel or order.
curl "https://api.lengow.io/v3.0/orders/?account_id=1&marketplace_order_id=xxxx"
{
"documents": [
{
"id": 14508010,
"marketplace_doc_id": "DELIVERY_240523V1163635879",
"url": "https://api.lengow.io/v3.0/document/14508010",
"created_at": "2024-05-24T08:19:34.818844Z",
"doc_type": {
"lengow_type": "DELIVERY",
"marketplace_code": "DELIVERY_NOTE",
"marketplace_label": "PinkConnect delivery notes"
}
}
]
}
2 steps to follow
1/ Retrieve the doc_id
Display the order details using the endpoint Get order with the query parameter marketplace_order_id
. Then in the JSON detail of each order, you will have access to the “documents” part, inside the "id".
2/ Download the document
Query
https://api.lengow.io/v3.0/document/<doc_id>?account_id=<account_id>
Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
doc_id | True | Integer | The identifier of the document, in the curl example is equal to "id": 14508010 |
account_id | True | Integer | Your account ID can be found in the 'General Information' section of your account. You will find your Account ID and your Customer ID on the left-hand side of this page. |
[GET] Zalando fulfillment Solution stock reports
Zalando generates two types of stock reports every day:
Daily "snapshot" report to monitor your performance called zfs-item-quantity- snapshot.
"One-shot" request to generate a specific stock report
To retrieve a specific snapshot, you need to make three API calls.
[GET] The different types of reports
Optional if you already know the name of the document type you are going to download
Query
https://api.lengow.io/v3.0/document/<feed_id>/list?account_id=<account_id>
curl "https://api.lengow.io/v3.0/document/222/list?account_id=111" -H "Content-Type: application/json"
Response 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
}
}
]
}
Query parameters
Parameter | Required | Type | Description |
---|---|---|---|
feed_id | True | Integer | Is the ID of one of your channels. |
account_id | True | Integer | Your account ID can be found in the 'General Information' section of your account. You will find your Account ID and your Customer ID on the left-hand side of this page. |
Check our guide to learn how to find the feed_id
The response will return two document-type
zfs-item- quantity-one-shot
zfs-item- quantity-snapshot
is_one_shot specify whether or not this document is stored. The document is directly streamed from the partner when the value is 'true'. Later, we will examine how this can change the process of retrieving a document
[GET] The list of a specific report type
Now that you have your report types, you have to list the available reports and choose the one to retrieve.
curl "https://api.lengow.io/v3.0/document/222/zfs-item-quantity-snapshot/list?account_id=111" -H "Content-Type: application/json"
Response:
{
"13027": {
"created_at":"2022- 04-22T00:18:10.416Z",
"type":"application/ csv",
"errors": null,
"status": "ready"
}
}
Query
GET https://api.lengow.io/v3.0/document/<feed_id>/<document_type>/list?account_id=<account_id>
Reports type. They are two types: “zfs-item- quantity-one-shot” and “zfs-item- quantity-snapshot”
On the example on the right side, 13027 is the document ID, you will need this ID to retrieve the document later.
The data retrieved enables you to choose which report 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.
[GET] Downloading the report
Once you have identified the document ID you need, you will have to download it.
curl "https://api.lengow.io/v3.0/document/222/zfs-item-quantity-snapshot/download/13027?account_id=111" -H "Content-Type: application/json"
Response:
"ean","total_quantity","total_ offerable_quantity","total_ non_offerable_quantity"," location_id","location_ quantity","location_offerable_ quantity","location_non_ offerable_quantity"
"0194502370669","1","0","1"," 1e57b2b6-907b-4676-8766- 339a1d596e59","1","0","1"
Query https://api.lengow.io/v3.0/document/<feed_id>/<document_type>/download/<doc_id>?account_id=<account_id>
[POST] Your invoice in Lengow API
Amazon VCS
curl --location 'api.lengow.io/v3.0/document' \
--header 'Authorization: null' \
--form 'order_id="402-5089520-9826756"' \
--form 'account_id="12564"' \
--form 'metadata="{\"doc_type\": \"INVOICE\", \"DocumentId\": \"00595808_51741\", \"ShippingId\": \"DLtz8hSG2\"}"' \
--form 'marketplace="amazon_fr"' \
--form 'upload=@"/C:/Users/Morvan.cabioc'\''h/Downloads/00595808_51741 (1).pdf"'
The whole Amazon invoice process is detailed at the section Amazon VCS.
Once you have created your invoice Amazon, you can upload it to our API through a POST using the endpoint document, then it will be sent to Amazon.
Mirakl Marketplaces
curl --location 'https://api.lengow.io/api/v3.1/document/' \
--form 'order_id="5137116-A"' \
--form 'account_id="58"' \
--form 'metadata="{\"document_number\":\"123\",\"issue_date\":\"2024-10-17T00:00:00Z\",\"due_date\":\"2024-10-18T00:00:00Z\",\"total_amount_excluding_taxes\":31.99,\"total_tax_amount\":3.19}"' \
--form 'marketplace="decathlon_eu_be_fr"' \
--form 'upload=@"/C:/Users/jerom/Desktop/invoice.pdf"'
Upload your invoices through our API to Mirakl using the document endpoint. Reflect the marketplace within the marketplace
form input. Currently, this feature is restricted to decathlon_eu_be_fr
. Requires document metadata to be provided :
document_number
: Invoice number following your own numbering rules sent as a stringissue_date
: Invoice issued date sent as a string following the ISO pattern YYYY-mm-ddTHH:MM:ssZdue_date
: Invoice due date sent as a string following the ISO pattern YYYY-mm-ddTHH:MM:ssZtotal_amount_excluding_taxes
: Total invoice amount without taxes sent as a floattotal_tax_amount
: Total tax amount sent as a float