NAV
cURL

API Release Notes

Release note are structured as follows:

  1. 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
  2. Impacted: Which API will be impacted by the changes
  3. Release date: Date when changes will be deployed in production
  4. Description: The content of changes

Current Release

Released

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

Example

curl https://api.lengow.io/v3.0/preprocessing/job/?account_id=1&catalog=1

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

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

Getting started

Welcome to Lengow API documentation.

Lengow API is a REST-based API that allows you to:

Technical Aspect

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:

  1. Order is placed on a marketplace
  2. Order is retrieved from the marketplace by Lengow every 15 minutes
  3. 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.
  4. 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.
  5. 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.
  6. 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

ORDER_WORKFLOW

[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

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:

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
email String Email
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.

[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 VCS

Getting started with Amazon VCS

Amazon VCS is a service reserved to business customers (B2B) and it stands for Amazon VAT Calculation Service (VCS). Amazon’s VAT Calculation Service (VCS) allows Sellers to show VAT exclusive prices to Business Customers and get the Downloadable VAT Invoice badge.

These endpoints will be available only if the Amazon VCS App is activated on your Lengow account. The VIDR data will be available only if your Amazon account is enrolled in the Amazon VCS program.

Please refer to [Amazon VCS documentation]((https://m.media-amazon.com/images/G/01/B2B/DeveloperGuide/vat_calculation_service_dev_guide_H383rf73k4hsu1TYRH139kk134yzs._CB1537356429.pdf) and our Amazon VCS guide for further information.

Method Endpoint Description
GET https://api.lengow.io/v3.0/apps/amazon-vcs/vidr/ This endpoint allows you to retrieve VAT Invoice Data Report (VIDR) of Amazon for invoices and credit notes. This VIDR report will be useful to create your invoice.

Through this API you will have access to:

Good to know:

[GET] VAT Invoice Data Report

curl https://api.lengow.io/v3.0/apps/amazon-vcs/vidr/?account_id=1&marketplace=amazon_de&marketplace_order_id=XXX-XXXXXXX-XXXXXXX -X GET -H "Content-Type: application/json"

{
  "account_id": 1,
  "marketplace": "amazon_de",
  "data": [
    {
      "marketplace-id": "DE",
      "order-id": "XXX-XXXXXXX-XXXXXXX",
      "order-item-id": "9060338888888",
      "shipping-id": "D1cjkekMD",
      "transaction-id": "amzn1:crow:7/C3di34jfQDWtqxpbXQBADg",
      "transaction-type": "RETURN",
      "invoice-number": "",
      "invoice-status": "CreditNotePending",
      "invoice-status-description": "Credit Note is due. The return has been accepted.",
      "is-amazon-invoiced": "FALSE",
      "order-date": "2/20/2019 14:11",
      "shipment-date": "2/26/2019 20:14",
      "buyer-vat-number": "",
      "seller-vat-number": "DEXXXXXXXX",
      "asin": "B0774XXXXX",
      "sku": "12-rrrr-AAAA",
      "product-name": "Soundbar Bracket braket",
      "quantity-purchased": "1",
      "currency": "GBP",
      "item-vat-incl-amount": "-19.17",
      "item-vat-amount": "-3.06",
      "item-vat-excl-amount": "-16.11",
      "item-vat-rate": "0.19",
      "item-promo-vat-incl-amount": "0",
      "item-promo-vat-excl-amount": "0",
      "item-promo-vat-amount": "0",
      "item-promo-vat-rate": "0",
      "item-promotion-id": "",
      "gift-wrap-vat-incl-amount": "0",
      "gift-wrap-vat-amount": "0",
      "gift-wrap-vat-excl-amount": "0",
      "gift-wrap-vat-rate": "0",
      "gift-promo-vat-incl-amount": "0",
      "gift-promo-vat-excl-amount": "0",
      "gift-promo-vat-amount": "0",
      "gift-promo-vat-rate": "0",
      "gift-promotion-id": "",
      "shipping-vat-incl-amount": "0",
      "shipping-vat-amount": "0",
      "shipping-vat-excl-amount": "0",
      "shipping-vat-rate": "0",
      "shipping-promo-vat-incl-amount": "0",
      "shipping-promo-vat-excl-amount": "0",
      "shipping-promo-vat-amount": "0",
      "shipping-promo-vat-rate": "0",
      "ship-promotion-id": "",
      "is-business-order": "FALSE",
      "price-designation": "",
      "purchase-order-number": "",
      "recipient-name": "Harry Potter",
      "ship-service-level": "Expedited",
      "fulfilled-by": "FBA",
      "ship-address-1": "4",
      "ship-address-2": "",
      "ship-address-3": "Little Whinging",
      "ship-city": "Surrey",
      "ship-state": "",
      "ship-postal-code": "AAA 333",
      "ship-country": "GB",
      "ship-phone-number": "040/1111111",
      "ship-from-country": "DE",
      "ship-from-state": "Lower Saxony",
      "ship-from-city": "Winsen",
      "ship-from-postal-code": "23132",
      "billing-name": "Privet Drive",
      "bill-address-1": "4",
      "bill-address-2": "",
      "bill-address-3": "Little Whinging",
      "bill-city": "Surrey",
      "bill-state": "",
      "bill-postal-code": "AAA 333",
      "bill-country": "GB",
      "billing-phone-number": "040/0999999",
      "buyer-name": "Harry Potter",
      "buyer-company-name": "ABC Company Ltd.",
      "legacy-customer-order-item-id": "13143135999999",
      "recommended-invoice-format": "PDF",
      "buyer-tax-registration-type": "",
      "buyer-e-invoice-account-id": "",
      "is-buyer-physically-present": "",
      "is-seller-physically-present": "",
      "citation-es": "",
      "citation-it": "",
      "citation-fr": "",
      "citation-de": "",
      "citation-en": ""
    },
    {
      "marketplace-id": "DE",
      "order-id": "XXX-XXXXXXX-XXXXXXX",
      "order-item-id": "9060337777777",
      "shipping-id": "D1cjkekMD",
      "transaction-id": "D1cjkekMD",
      "transaction-type": "SHIPMENT",
      "invoice-number": "",
      "invoice-status": "InvoicePending",
      "invoice-status-description": "Invoice is due. The shipment has been dispatched.",
      "is-amazon-invoiced": "FALSE",
      "order-date": "2/20/2019 14:11",
      "shipment-date": "2/27/2019 20:57",
      "buyer-vat-number": "",
      "seller-vat-number": "DEXXXXXXXX",
      "asin": "B07BRSSSSS",
      "sku": "11-1222-1XDS",
      "product-name": "XXXXXX f\u0081r Bosch Siemens Samsung Rowenta Grundig Dirt Devil",
      "quantity-purchased": "10",
      "currency": "EUR",
      "item-vat-incl-amount": "149",
      "item-vat-amount": "23.8",
      "item-vat-excl-amount": "125.2",
      "item-vat-rate": "0.19",
      "item-promo-vat-incl-amount": "0",
      "item-promo-vat-excl-amount": "0",
      "item-promo-vat-amount": "0",
      "item-promo-vat-rate": "0",
      "item-promotion-id": "",
      "gift-wrap-vat-incl-amount": "0",
      "gift-wrap-vat-amount": "0",
      "gift-wrap-vat-excl-amount": "0",
      "gift-wrap-vat-rate": "0",
      "gift-promo-vat-incl-amount": "0",
      "gift-promo-vat-excl-amount": "0",
      "gift-promo-vat-amount": "0",
      "gift-promo-vat-rate": "0",
      "gift-promotion-id": "",
      "shipping-vat-incl-amount": "3.99",
      "shipping-vat-amount": "0.64",
      "shipping-vat-excl-amount": "3.35",
      "shipping-vat-rate": "0.19",
      "shipping-promo-vat-incl-amount": "0",
      "shipping-promo-vat-excl-amount": "0",
      "shipping-promo-vat-amount": "0",
      "shipping-promo-vat-rate": "0",
      "ship-promotion-id": "",
      "is-business-order": "FALSE",
      "price-designation": "",
      "purchase-order-number": "",
      "recipient-name": "Harry Potter",
      "ship-service-level": "Expedited",
      "fulfilled-by": "FBA",
      "ship-address-1": "4",
      "ship-address-2": "",
      "ship-address-3": "Little Whinging",
      "ship-city": "Surrey",
      "ship-state": "",
      "ship-postal-code": "AAA 333",
      "ship-country": "GB",
      "ship-phone-number": "040/1111111",
      "ship-from-country": "DE",
      "ship-from-state": "Lower Saxony",
      "ship-from-city": "Winsen",
      "ship-from-postal-code": "23132",
      "billing-name": "Privet Drive",
      "bill-address-1": "4",
      "bill-address-2": "",
      "bill-address-3": "Little Whinging",
      "bill-city": "Surrey",
      "bill-state": "",
      "bill-postal-code": "AAA 333",
      "bill-country": "GB",
      "billing-phone-number": "040/0999999",
      "buyer-name": "Harry Potter",
      "buyer-company-name": "ABC Company Ltd.",
      "legacy-customer-order-item-id": "13143135555555",
      "recommended-invoice-format": "PDF",
      "buyer-tax-registration-type": "",
      "buyer-e-invoice-account-id": "",
      "is-buyer-physically-present": "",
      "is-seller-physically-present": "",
      "citation-es": "",
      "citation-it": "",
      "citation-fr": "",
      "citation-de": "",
      "citation-en": ""
    }
  ]
}

Query Parameters

With filtering:

curl https://api.lengow.io/v3.0/apps/amazon-vcs/vidr/?account_id=1&marketplace=amazon_de&marketplace_order_id=XXX-XXXXXXX-XXXXXXX
Parameter Type Required
account_id Integer Yes
marketplace String Yes
marketplace_order_id String Optional, filter on data "order-id"
line String Optional, filter on data "order-item-id"
invoicing_status String Optional, filter on data "invoicing-status", e.g "InvoicePending"

Once you have retrieved VIDR, you can now go ahead and create the invoice/credit note on your side. You can find more information about the creation of your invoice/credit note in our Amazon VCS guide. When the document is ready, you will have to use our Documents endpoint to upload it on Amazon.

Possible errors:

HTTP 400

Create your invoice

Once you have retrieved VIDR, you can now go ahead and create the invoice/credit note on your side. For information, here is the list of mandatory information required by Amazon:

[POST] your invoice in Lengow API

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

Once you have created your invoice/credit voucher, you can upload it to our API through a POST, then it will be sent to Amazon. To execute this action use the endpoint document

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:

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

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 :

Order Documents

Document API allows to download or upload documents linked to orders, like invoices or credit notes.

This feature is specific to some marketplaces.

Get a document

Documents ids can be found in the orders API response

GET https://api.lengow.io/v3.0/document/<document_id>?account_id=1

Get a document

curl "https://api.lengow.io/v3.0/document/1?account_id=1"

Submit a document

POST https://api.lengow.io/v3.0/document/

This call requires a multipart/form-data content-type to post a document.

curl "https://api.lengow.io/v3.0/document" -X POST \
    -F account_id=1 \
    -F marketplace=amazon_de \
    -F order_id=XXX-XXXXXXX-XXXXXXX \
    -F order_line_id=linetest \
    -F upload=@<localfilename> \
    -F metadata="{\"doc_type\": \"INVOICE\", \"DocumentId\": \"123456\"}"

account_id and marketplace are mandatory parameters. If account_id is not filled, the request will result in a 401 Forbidden.

upload is a path to local filename. Using CURL, you must prefix it with an @.

metadata is serialized json. Required data may depend on marketplace and/or document. This example illustrates an Amazon VCS invoice.

For Amazon VCS:

After uploading the document, it is then possible to check the invoice_status and invoice_status_description through VIDR to know whether the document has been validated by Amazon or not.

This example illustrates an Amazon VCS invoice.

Possible errors:

HTTP 400

Specific VCS Errors:

HTTP 502 (JSON)

Example of HTTP POST request:

POST /api/v3.0/document/ HTTP/1.1
Content-Type: multipart/form-data; boundary=X--BOUNDARY
Accept: */*
Content-Length: 597

--X--BOUNDARY
Content-Disposition: form-data; name="order_id"
XXX-XXXXXXX-XXXXXXX
--X--BOUNDARY
Content-Disposition: form-data; name="account_id"
1
--X--BOUNDARY
Content-Disposition: form-data; name="marketplace"
amazon_de
--X--BOUNDARY
Content-Disposition: form-data; name="order_line_id"
linetest
--X--BOUNDARY
Content-Disposition: form-data; name="file"; filename="test_file"
Content-Type: application/octet-stream
filecontent
--X--BOUNDARY--
cURL