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

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

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

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

• 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 over HTTPS.
• All data is sent and received as JSON by default.

URL

Production URL: https://api.lengow.io

Specific types

Authentication

You need to authenticate yourself before making any request on the Lengow API.

[POST] Get a token

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

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

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.

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

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

• 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

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 to today - 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

Order sub-objects

The order object contains sub-objects, they are all defined underneath

Order object

Package object

A package groups all lines of an order by delivery address.

Ordered product

Address object

Tracking object

Payment object

Tax object

BuyerTax object

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

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

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"

Query Parameters

With filtering:

curl "https://api.lengow.io/v3.0/orders/actions/?account_id=1&marketplace_order_id=123456-ABC&marketplace=darty"

Response Schema application/json

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

Available action types

Available actions depend on the marketplace. Please refer you to the marketplace API.

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

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

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

Response Schema application/json

Parts of marketplace information

Detail of orders.actions part

Detail of depends_on fields / Conditional order action arguments

Detail of depends_on functions

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:

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

Documents

[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

[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

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 string
• issue_date : Invoice issued date sent as a string following the ISO pattern YYYY-mm-ddTHH:MM:ssZ
• due_date : Invoice due date sent as a string following the ISO pattern YYYY-mm-ddTHH:MM:ssZ
• total_amount_excluding_taxes : Total invoice amount without taxes sent as a float
• total_tax_amount : Total tax amount sent as a float