API - Best Practice for Orders API

If you are retrieving orders using Lengow's Orders API, make sure to follow our advice for an optimal use:

Authentication token

The session token returned by "access/get_token" is valid for one hour. You should not request a token before each request; otherwise, you may hit the rate limits and be blocked in your requests.

To find out how much time is left for a token, you can use the api /me which provides the expiration time of the current token.

Example:

curl --request GET \
 --url 'https://api.lengow.io/me' \
 --header 'Authorization: 69946b78-edae-49b8-8874-6fb025e09a58'

{
"token": "69946b78-edae-49b8-8874-6fb025e09a58",
"expire_at": "2022-12-21T13:56:08+00:00",
"account_id": 1,
"scopes": {
"feed_id": "*",
"account_id": 1,
"catalog_id": "*",
"product_id": "*"
}
}

Order retrieval

The Order List API features filters that enable several complementary approaches.

Finding new orders

The "merchant_order_id=None" filter parameter will only return orders for which the "merchant_order_id" is empty.
You can also limit the search period to speed up the query (e.g. the last three hours).

Example:

curl --request GET \
--url 'https://api.lengow.io/v3.0/orders/?account_id=1&merchant_order_id=None&marketplace_order_date_from=2022-12-21T12%3A22%2B01%3A00' \
--header 'Authorization: 69946b78-edae-49b8-8874-6fb025e09a58'

Each order can then be marked as "seen" with a merchant-specific identifier using the moi API (= merchant order id - Refer to our API documentation). As a result, marked orders will be absent from the next query.

Searching for updates

Orders have an "updated_at" field which is updated as soon as any information about the order is changed.
This date can be used to retrieve updated orders, by filtering using "updated_from" and "updated_to".

Example:

curl --request GET \
--url 'https://api.lengow.io/v3.0/orders/?account_id=1&updated_from=2022-12-21T14%3A22%2B01%3A00&updated_to=2022-12-21T15%3A22%2B01%3A00' \
--header 'Authorization: 69946b78-edae-49b8-8874-6fb025e09a58'

Pagination

The list of commands is paginated by a maximum of 100.

If an additional page is available, the "next" key in the JSON content contains the URL of the next page.
Otherwise, the "next" key is null, which means that the current page is the last.

Therefore, make sure to query the next page only if "next" is not null.

 Avoid simply iterating over the page number until you get a 404 (Not found) page, which is what happens when you request a page beyond the existing ones.
Even more, avoid iterating over a finite number of pages, which multiplies useless requests leading to 404 errors.

Example of the "next" key containing the URL of the next page:

{
"count": 4481,
"next": "https://api.lengow.io/v3.0/orders/?account_id=1&merchant_order_id=None&page=2",
"previous": null,
"results": [
    [...]

Actions on orders

Order actions are processed asynchronously. Sending a status update creates a task which is queued, and then processed by a separate process.

The response to the API call returns the task identifier, which can then be used to obtain the status and result of the task.

Example of an order action which has been processed:

curl --request GET \
--url 'https://api.lengow.io/v3.0/orders/actions/?account_id=1&id=81982959' \
--header 'Authorization: 69946b78-edae-49b8-8874-6fb025e09a58'

 "results": [
{
"id": 81982959,
"marketplace_order_id": "221219V2102418423",
"account_id": 1,
"marketplace": "veepee_pink_fr",
"action_type": "ship",
"processed": true,
"queued": false,
"tracking_number": "8G48609462340",
"tracking_url": "https://www.laposte.fr/outils/suivre-vos-envois?code=8G48609462340",
"carrier": "La Poste",
[...]
"created_at": "2022-12-21T11:17:47.353491Z",
"updated_at": "2022-12-21T11:17:48.408401Z",
[...]
}
]

You can track the status of each action with "queued" and "processed" fields:

• "queued" is "true" when the action is waiting for processing (or retrying on failure), and "false" when it is treated;
• "processed" is "true" when the action has been successful.

Rather than searching for past actions individually, it's more efficient to retrieve only those actions that require processing.

In the following example, we are looking for unsuccessful Veepee actions:

curl --request GET \
--url 'https://api.lengow.io/v3.0/orders/actions/?account_id=1&marketplace=veepee_pink_fr&processed=False&queued=False' \
--header 'Authorization: 69946b78-edae-49b8-8874-6fb025e09a58'

{
"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": 81428959,
"marketplace_order_id": "221211V1101346433",
"account_id": 223,
"marketplace": "veepee_pink_fr",
"action_type": "ship",
"processed": false,
"queued": false,
[...]
"errors": "Rate limit exceeded.",

Note: the answer is paginated like a command list, use "next" to follow the next page.

Marketplaces API

The data provided by the Marketplaces API changes very little.

It is therefore unnecessary to request it more than once an hour, or even less.