API - Use cases

Find here some tips and use cases to help you set your requests and actions with our API.

In order to illustrate these use cases, we have chosen to use a test merchant.

Let's call our test merchant "Julia" and say that her account number is "1".
Please note that she is using Postman to make all her API calls.
Results will be in JSON format
These use cases are pure examples

More info about Postman and how to create a collection (group of saved request) here.

Connect to our API: Get access token

First step before making a request call or any action within the Lengow API is to enter the API.

To do so, Julia needs to collect her credentials from her Lengow account that are:

- Lengow account ID

- secret token

- token

and open Postman.

Then, once she has set a new environment into Postman with her credentials she can proceed and POST the first call which is:

POST /access/get_token

The API sends back an access token such as this one:

{
    "token": "69946b78-edae-49b8-8874-6fb025e09a58",
    "account_id": 1
}

She adds this token to her Postman environment under the variable LENGOW_AUTH (see image below).

The "token" sent out by the Lengow API lasts 3600 seconds and can now be used as Lengow_AUTH in Postman.

Tip: With the help of your developers you can set up a script that makes this call automatically every hour.

Check actions on orders

Julia has corrected one of her ship action on an orders. She wants to check that her last action is correct and that the action she sent has been correctly processed by the Lengow API towards the channel's API.

GET /orders/actions/

From the Lengow API, she queries this specific order using the "&marketplace_order_id" parameter and use the ID of her order (see below).

-- endpoint /orders/actions --

-- GET method --

GET /orders/actions/?account_id=1&marketplace_order_id=12-05319-12345

-- API response --

{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": 13244460,
"marketplace_order_id": "12-05319-123452",
"account_id": 1,
"marketplace": "ebay_fr",
"action_type": "ship",
"processed": true,
"queued": false,
"tracking_number": "2L01286914523",
"tracking_url": null,
"carrier": "FR_ColiposteColissimoRecommended",
"custom_carrier": null,
"line": "193393034918-1749999860009",
"declared_value": null,
"currency_code": null,
"invoice_number": null,
"shipping_method": null,
"shipping_date": null,
"shipping_service_id": null,
"shipping_service_offer_id": null,
"created_at": "2020-07-02T08:03:37.912433Z",
"updated_at": "2020-07-02T08:03:39.262053Z",
"weight": null,
"weight_unit": null,
"comment": null,
"delay": null,
"reason": null,
"charges": null,
"errors": null,
"delivery_date": null,
"delivery_experience": null,
"return_tracking_number": null,
"refund_price": null,
"refund_shipping_price": null,
"refund_mode": null,
"refund_reason": null,
"refund_quantity": null,
"refund_shipping": null,
"refund_shipping_taxes": null,
"refund_taxes": null,
"carrier_name": null,
"carrier_pickup": null,
"package_dimension_length": null,
"package_dimension_width": null,
"package_dimension_height": null,
"package_dimension_unit": null,
"from_address_name": null,
"from_address_line": null,
"from_address_city": null,
"from_address_state_province": null,
"from_address_postal_code": null,
"from_address_country_code": null,
"from_address_mail": null,
"from_address_phone": null,
"pickup_id": null,
"refund_id": null,
"return_carrier": null
},
{
"id": 13244455,
"marketplace_order_id": "12-05319-123452",
"account_id": 1,
"marketplace": "ebay_fr",
"action_type": "ship",
"processed": false,
"queued": false,
"tracking_number": null,
"tracking_url": null,
"carrier": "FR_ColiposteColissimoRecommended",
"custom_carrier": null,
"line": "193393034918-1749999860009",
"declared_value": null,
"currency_code": null,
"invoice_number": null,
"shipping_method": null,
"shipping_date": null,
"shipping_service_id": null,
"shipping_service_offer_id": null,
"created_at": "2020-07-02T08:02:50.609088Z",
"updated_at": "2020-07-02T08:02:50.681358Z",
"weight": null,
"weight_unit": null,
"comment": null,
"delay": null,
"reason": null,
"charges": null,
"errors": "Tracking needs number AND carrier for ship order action",
"delivery_date": null,
"delivery_experience": null,
"return_tracking_number": null,
"refund_price": null,
"refund_shipping_price": null,
"refund_mode": null,
"refund_reason": null,
"refund_quantity": null,
"refund_shipping": null,
"refund_shipping_taxes": null,
"refund_taxes": null,
"carrier_name": null,
"carrier_pickup": null,
"package_dimension_length": null,
"package_dimension_width": null,
"package_dimension_height": null,
"package_dimension_unit": null,
"from_address_name": null,
"from_address_line": null,
"from_address_city": null,
"from_address_state_province": null,
"from_address_postal_code": null,
"from_address_country_code": null,
"from_address_mail": null,
"from_address_phone": null,
"pickup_id": null,
"refund_id": null,
"return_carrier": null
}
]
}

API response

The Lengow API response indicates that 2 actions were made on this order:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {

In the results, you can see that the order id appears twice. It means that the server shows the same order twice because two actions were made. The last action is shown at the top of the response.

At the very bottom of the response look at the following parameters:

"action_type"
"processed"
"queued"
"error"

1/ The first “ship” action, Julia sent earlier, is not valid because we see in the API response:

"processed": false
"error": "Tracking needs number AND carrier for ship order action"

Here, eBay API is telling Lengow's API, that Julia's "ship" action is incomplete because one or more parameters were missing.

You can see that parameter "tracking_number" is null in the first "ship" action.

2/ The second "ship" action is valid because:

"processed": true
"queued": false
"error": null

More info on "queued" and "processed" object here.

Get Shipment information on orders

Julia, our test merchant, received a new order from La Redoute marketplace. She wants to find the requested shipping information to help her ship the order.

It means, that she wants to know what information she must complete to correctly send her order.

STEP 1

Once connected to the Lengow API, she queries her order (see below) using the /orders endpoint like this:

GET /orders/?account_id=1&marketplace_order_id=2020.111.123456789

{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"marketplace": "laredoute",
"account_id": 1,
"marketplace_country_iso2": "FR",
"marketplace_order_id": "2020.111.123456789",
"merchant_order_id": [
"1234567"
],
"marketplace_status": "ToShip",
"lengow_status": "waiting_shipment",
"workflow_rank": 5,
"marketplace_order_date": "2020-11-12T15:23:18Z",
"total_order": 74.8,
"total_tax": "0.00",
"shipping": 9.9,
"discount": 0.0,
"commission": null,
"processing_fee": null,
"currency": {
"iso_a3": "EUR",
"symbol": "€",
"name": "Euro"
},
"original_currency": {
"iso_a3": "EUR",
"symbol": "€",
"name": "Euro"
},
"original_total_order": 74.8,
"original_total_tax": "0.00",
"original_shipping": 9.9,
"original_discount": 0.0,
"original_commission": null,
"original_processing_fee": null,
"comments": null,
"invoice_number": null,
"invoice_url": null,
"payments": [],
"packages": [
{
"cart": [
{
"id": 8623271,
"marketplace_order_line_id": "2020.111.123456789-1",
"marketplace_product_id": "4001072020053",
"merchant_product_id": {
"field": "ID_PRODUCT",
"id": "111111"
},
"feed_id": 12345,
"marketplace_package_id": null,
"marketplace_status": "ToShip",
"lengow_status": "waiting_shipment",
"title": "Visionneuse diapositive automatique - Diascop 3",
"category": "Accueil > Accessoires > Visionneuses",
"url_product": null,
"url_image": null,
"order_line_meta": {
"DeliveryMode": "Home",
"DeliveryType": "Regular"
},
"amount": "64.90",
"tax": "0.00",
"discount": null,
"shipping": null,
"original_amount": "64.90",
"original_tax": "0.00",
"original_discount": null,
"original_shipping": null,
"quantity": 1,
"documents": [],
"created_at": null,
"updated_at": null,
"orderline_types": []
}
],
"delivery": {
"id": 151186892,
"type": "delivery",
"first_line": "500 AVENUE TEST",
"zipcode": "69300",
"city": "CALUIRE ET CUIRE",
"vat_number": null,
"company": null,
"civility": "Monsieur",
"first_name": null,
"last_name": null,
"second_line": "",
"complement": "ETAGE 3E",
"phone_home": null,
"phone_office": null,
"phone_mobile": "06700000000",
"full_address": null,
"full_name": "TEST BOB DUPONT",
"email": "*****.fr",
"metas": null,
"state_region": null,
"common_country_iso_a2": "FR",
"trackings": [
{
"number": null,
"method": "Home / Regular",
"carrier": null,
"url": null,
"is_delivered_by_marketplace": null,
"parcel_weight": null,
"shipped_at": null,
"pickup_store": {
"id": null
},
"relay": {
"id": null,
"name": null
},
"marketplace_order_line_ids": [
"2020.111.123456789-1"
]
}
]
}
}
],
"billing_address": {
"id": 151198390,
"type": "billing",
"first_line": "500 AVENUE TEST",
"zipcode": "69300",
"city": "CALUIRE ET CUIRE",
"vat_number": null,
"company": null,
"civility": "Monsieur",
"first_name": null,
"last_name": null,
"second_line": "",
"complement": "ETAGE 3E",
"phone_home": null,
"phone_office": null,
"phone_mobile": "06700000000",
"full_address": null,
"full_name": "TEST BOB DUPONT",
"email": "*****.fr",
"metas": null,
"state_region": null,
"common_country_iso_a2": "FR"
},
"contact_address": null,
"documents": [],
"imported_at": "2020-11-12T16:09:07.256186Z",
"updated_at": "2020-11-12T16:32:15.849000Z",
"order_meta": {
"checksum": "b4aa946ef504ed758359db880c03bd62"
},
"anonymized": false,
"order_types": []
}
]
}

The order is in the "waiting_shipment" status.

From the "delivery" > "trackings" parameter of the API response, Julia can check the delivery method chosen by the customer:

"method": "Home / Regular"

From this "tracking" parameter, other information can be found and could be completed depending on the delivery method chosen by the customer:

"is_delivered_by_marketplace": null,

"pickup_store": { "id": null },

"relay": { "id": null, "name": null

Note: If the "Relais / Regular" method had been chosen, the "relay" parameter of the order would have been completed with an Identifier and a name of the relay point.

STEP 2

Julia then queries the overall marketplace information in order to know what are the mandatory elements to fill in to correctly ship her order.

From the API, this time she uses the endpoint /marketplace:

GET /marketplaces/?marketplace=laredoute

In the response that the Lengow API returns, she could find

list of order status
Authorized actions on orders and mandatory parameters to complete per action
Authorized carriers by the marketplace in the "carriers" tag

For La Redoute, she finds:

 "actions": {
                "ship": {
                    "args": [
                        "carrier",
                        "tracking_number"
                    ],

Then she consults the "carrier" tag to know if valid values are mandatory or not:

"carrier": {
                            "type": "string",
                            "valid_values": {},
                            "default_value": "",
                            "accept_free_values": true

This means that to validate the shipment of her La Redoute order (home delivery), Julia must provide

the "carrier" information
a "tracking_number"

As there is no list of mandatory carriers, she can use the carrier of her choice.

Retrieve documents

Julia, our test merchant, received a new order from Zalando marketplace. She wants to download the documents she is requested to enclose in the parcel: invoice, delivery note and return form.

Note: These documents are edited by Lengow and may also be downloaded on the Lengow platform, as explained in our Zalando guide.

STEP 1

Once connected to the Lengow API, she queries her order using the /orders endpoint like this:

GET /orders/?account_id=1&marketplace_order_id=10987654321

In the response that the Lengow API returns, she finds the "documents" section, where she can get the IDs of these documents:

"documents": [
{
"id": 2111112,
"marketplace_doc_id": "DELIVERY_NOTE_123fc456-f789-101b-b12g-a134c1235678",
"url": "http://api.lengow.io/v3.0/document/2111112",
"created_at": "2022-05-14T06:26:19.479581Z",
"doc_type": {
"lengow_type": "DELIVERY",
"marketplace_code": "DELIVERY_NOTE",
"marketplace_label": "Zalando delivery notes"
}
},
{
"id": 2111111,
"marketplace_doc_id": "RETURN_123fc456-f789-101b-b12g-a134c1235678",
"url": "http://api.lengow.io/v3.0/document/2111111",
"created_at": "2022-05-14T06:26:19.478343Z",
"doc_type": {
"lengow_type": "RETURN",
"marketplace_code": "RETURN",
"marketplace_label": "Zalando return form"
}
},
{
"id": 2111110,
"marketplace_doc_id": "BILL_123fc456-f789-101b-b12g-a134c1235678",
"url": "http://api.lengow.io/v3.0/document/2111110",
"created_at": "2022-05-14T06:26:19.475280Z",
"doc_type": {
"lengow_type": "BILL",
"marketplace_code": "BILL",
"marketplace_label": "Zalando invoice"
}
}
]

STEP 2

Using the document IDs she found (2111110, 2111111 and 2111112 in this example), Julia downloads the corresponding documents using the /document endpoint (one call for each document):

GET /document/2111110?account_id=1

Result as visible in Postman:

Lengow

Updated January 25, 2024 11:27

Connect to our API: Get access token

Check actions on orders

Get Shipment information on orders

Retrieve documents

Articles in this section