NAV
cURL

API Release Note

Release note are structured as follow:

  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 functionnalities which will be deprecated
    • Removal - API functionnalities 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

Next Release

Current Release

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

Released

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:

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

Overview

Content-Type and Accept Headers

curl https://api.lengow.io/v3.0/orders/ -X OPTIONS --header "Accept: application/json"

If you want to change the returned data format, you can set the Accept header. The server will response you with the given format and change the Content-Type header.

By default, the format is "application/json".

To get all accepted format, you can use the OPTIONS method.

API types

Basic type Description or aliases
String String
Integer Integer
Decimal Decimal, Float
Boolean Boolean
Array Array, List
Object Object, Json
Country Depending on ressource, countries are specified as two (ISO 3166-2) or three characters
Date All date/time values are specified in ISO 8601
Currency All currencies are specified as three characters (ISO 4217)
None None, null, nothing

All monetary amounts like prices are specified as decimal number.

When the API accepts or returns several types, the format is as followed Array, String.

HTTP Response Codes

Below is a non-exhaustive list of HTTP response codes used by the API. For more information, see the List of HTTP code status.

Code Text Description
200 OK Success
201 Created The request has been fulfilled, a new resource has been created.
202 Accepted The request needs asynchronous action to create the resource, but is correct and as been accepted.
400 Bad Request The request has not been processed because of a client error (bad request syntax, invalid arguments...). See accompanying message for more information.
401 Access not granted Authentication is required for this request and has failed.
403 Forbidden User is not allowed to access this resource.
404 Not Found The request resource could not be found.
429 Request limitation reached Too many requests have been made in a too short amount of time.
530 Logical Error The request has failed probably due to bad input parameters (catalog that does not exist, invalid search rules...). See accompanying message for more information.
540 Technical Error The request has failed due to an internal error. See accompanying message for more information.

Authentication

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

Get a token

curl "https://api.lengow.io/access/get_token" -X POST --data "access_token=XXXXX&secret=XXXXX"
{"token": "6b7280eb-e7d4-4b94-a829-7b3853a20126", "account_id": 1}

First, you'll need to get a token. Each token has a lifetime of 3600 seconds.

POST https://api.lengow.io/access/get_token

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 --header "Authorization: 6b7280eb-e7d4-4b94-a829-7b3853a20126"

Once you have your token, all your API request will need a Authorization header.

Orders

Specific order type reference Description
Package Informations about package, its delivery and 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

Orders Status

Each marketplaces have their own status. In Lengow, all these status are transformed in a Lengow status.

List of all Lengow status :

Status Allowed action Description
new None Order was created but no action are available for now.
waiting_acceptance accept,refuse The merchant has to accept the order.
refused None The order was refused by the merchant.
accepted None The order has been accepted by the merchant and waiting the marketplace authorization for shipping.
waiting_shipment ship The merchant has to ship the order.
shipped None The order is waiting the final marketplace validation for closing.
closed None The order is closed, no more action are available.
canceled refund The order was canceled. Depending on marketplace, you can refund the order.
refunding None The refund demand is waiting the marketplace validation.
refunded None Like closed status, the order is closed and no more action are available.
pickup_to_prepare None The merchant has to prepare the pick up.
to_pickup None The order is ready for pick up.
pickup_completed None The order has been picked up by the buyer.
pickup_canceled None The pick up has been canceled.
to_refund refund The merchant has to refund the order.

Simple call :

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

Get orders

GET https://api.lengow.io/v3.0/orders/

This API allows you to retrieve your orders.

With pagination :

curl https://api.lengow.io/v3.0/orders/?account_id=1&page=5&page_size=50

Pagination

The result is paginated and differents arguments can be provide to manage this pagination.

Field Type Default Description
page Integer 1 The page number
page_size String 100 Maximum 100. Number of results by page

Ordering

With ordering :

curl https://api.lengow.io/v3.0/orders/?account_id=1&ordering=marketplace,-updated_at

You can control the ordering of results with the ordering parameter. For reversing the ordering, your can prefix your field by -.

The default ordering is marketplace,-marketplace_order_date,-imported_at.

List of supported ordering fields:

Argument Type
marketplace String
marketplace_order_id String
merchant_order_id String
lengow_status String
marketplace_status String
marketplace_order_date Date
imported_at Date
updated_at Date

Filtering

With filtering :

curl https://api.lengow.io/v3.0/orders/?account_id=1&marketplace=menlook

You can filter the result with differents filters. account_id is a mandatory filter.

By default, the marketplace_order_date_from filter is setted to current day - 7 days.

You can search a specific order by its marketplace_order_id by providing couple of filters (marketplace_order_id - marketplace). This couple is mandatory, in other case the API will use its befault behaviour (current day - 7 days).

List of supported fields:

Filter Type
account_id Integer
marketplace String
marketplace_order_id String
merchant_order_id String, None to get empty values
lengow_status String
marketplace_status String
marketplace_order_date_from Date
marketplace_order_date_to Date
imported_from Date
imported_to Date
updated_from Date
updated_to Date

Changing the currency

With set_currency :

curl https://api.lengow.io/v3.0/orders/?account_id=1&set_currency=USD

By default, all amount fields are returned in your account's currency.

If you want to change the currency, you can use the set_currency parameter. The value must be specified as three characters (ISO 4217).

An example of returned orders :

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "marketplace": "amazon_uk",
            "account_id": 1,
            "marketplace_country_iso2": "GB",
            "marketplace_order_id": "order1",
            "merchant_order_id": null,
            "marketplace_status": "Shipped",
            "lengow_status": "shipped",
            "workflow_rank": 6,
            "marketplace_order_date": "2019-03-22T17:54:34.369000Z",
            "total_order": 809.2900000000001,
            "total_tax": "134.45",
            "shipping": 2.6,
            "discount": 0,
            "commission": "-56.47",
            "processing_fee": null,
            "currency": {
                "iso_a3": "EUR",
                "symbol": "€",
                "name": "Euro"
            },
            "original_currency": {
                "iso_a3": "GBP",
                "symbol": "£",
                "name": "British Pound"
            },
            "original_total_order": 701.25,
            "original_total_tax": "116.50",
            "original_shipping": 2.25,
            "original_discount": 0,
            "original_commission": "-48.93",
            "original_processing_fee": null,
            "original_total_buyer_amount": 1.00,
            "original_total_buyer_tax": 1.55,
            "original_buyer_currency": "EUR",
            "comments": null,
            "invoice_number": null,
            "invoice_url": null,
            "payments": [
                {
                    "id": 1,
                    "checkout": null,
                    "status": null,
                    "type": "Other: Standard",
                    "settled_at": null,
                    "payment_terms": null,
                    "channel_order_marketplace": 1
                }
            ],
            "packages": [
                {
                    "cart": [
                        {
                            "id": 1,
                            "marketplace_order_line_id": "line1",
                            "marketplace_product_id": "product1",
                            "merchant_product_id": {
                                "field": "ID_PRODUCT",
                                "id": "Product1"
                            },
                            "feed_id": 1,
                            "marketplace_package_id": null,
                            "marketplace_status": "Shipped",
                            "lengow_status": "shipped",
                            "title": "Product TEST",
                            "category": null,
                            "url_product": null,
                            "url_image": null,
                            "order_line_meta": {
                            },
                            "amount": "806.69",
                            "tax": "134.45",
                            "discount": null,
                            "shipping": "2.60",
                            "original_refunded_amount": "0.00",
                            "refunded_amount": "0.00",
                            "original_amount": "699.00",
                            "original_tax": "116.50",
                            "original_discount": null,
                            "original_shipping": "2.25",
                            "quantity": 1,
                            "max_shipping_date": "2019-03-25T11:48:09.071000Z",
                            "created_at": null,
                            "updated_at": null,
                            "original_buyer_tax": null,
                            "original_buyer_amount": null,
                        }
                    ],
                    "delivery": {
                        "id": 1,
                        "type": "delivery",
                        "first_line": "1 Rue de la Paix",
                        "zipcode": "44",
                        "city": "Nantes",
                        "company": null,
                        "civility": null,
                        "first_name": null,
                        "last_name": null,
                        "second_line": null,
                        "complement": null,
                        "phone_home": null,
                        "phone_office": null,
                        "phone_mobile": null,
                        "full_address": null,
                        "full_name": "Dupont",
                        "email": "test@lengow.amazon.co.uk",
                        "metas": null,
                        "state_region": "",
                        "common_country_iso_a2": "GB",
                        "trackings": [
                            {
                                "number": null,
                                "method": "Standard",
                                "carrier": null,
                                "url": null,
                                "is_delivered_by_marketplace": true,
                                "parcel_weight": null,
                                "shipped_at": null,
                                "relay": {
                                    "name": null,
                                    "id": null,
                                    "type": null
                                },
                                "marketplace_order_line_ids": [
                                    "line1"
                                ]
                            }
                        ]
                    }
                }
            ],
            "billing_address": {
                "id": 2,
                "type": "billing",
                "first_line": null,
                "zipcode": "44",
                "city": "Nantes",
                "company": null,
                "civility": null,
                "first_name": null,
                "last_name": null,
                "second_line": null,
                "complement": null,
                "phone_home": null,
                "phone_office": null,
                "phone_mobile": null,
                "full_address": null,
                "full_name": "Dupont",
                "email": "test@lengow.amazon.co.uk",
                "metas": null,
                "state_region": "",
                "common_country_iso_a2": "GB"
            },
            "contact_address": null,
            "imported_at": "2019-03-22T20:05:35.196060Z",
            "updated_at": "2019-03-25T11:48:09.071000Z",
            "order_meta": {
                "checksum": "fffffffggghghhgu"
            },
            "tax": {
                "order_tax_id": "T4X-1D",
                "is_marketplace_deemed_supplier": true,
                "tax_electronic_portal_type": "OSS",
                "tax_electronic_portal_id": "OSS-1234",
                "marketplace_eori_number": "EORI-5555",
                "buyer_tax": {
                    "type": "VATIN",
                    "id": "123789",
                },
            },
            "anonymized": false
        }
    ]
}

Results

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 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 than lengow_status.
total_order Decimal Order price (shipping price and taxes included)
total_tax Decimal Order tax
commission Decimal Marketplace commission
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 the orders older than 6 months.

Package object

A package group all line 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 exemple. = 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

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

PATCH https://api.lengow.io/v3.0/orders/moi/

You can import your owns order identifiers in the Lengow systems.

Request

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, the order object will be send.

Get all actions on orders

Simple call :

curl https://api.lengow.io/v3.0/orders/actions/?account_id=1

GET https://api.lengow.io/v3.0/orders/actions/

Filtering

You can filter the result with different filters. account_id is a mandatory filter.

With filtering :

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

List of supported filters:

Filter Type
id Integer
account_id Integer
marketplace String
marketplace_order_id String
action_type String
processed Boolean
queued Boolean
tracking_number String
carrier String
line String
created_from Date
created_to Date
updated_from Date
updated_to Date
errors String

Result

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 Is the action processed by marketplace ?
queued Boolean Lengow still trying to make this action on the marketplace.
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. To have the final error, you should wait that queued becomes false.

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.

Available action types

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 order's delivery date (currently only available for El Corte Ingles)
set_eligible_shipping_methods Retrieve eligible shipping methods for 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)

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

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",
   "carrier": "ups"
}

POST https://api.lengow.io/v3.0/orders/actions/

With this API, you can make actions on your orders.

These actions will be sent asynchronously to the partner, and retried three times on failure.

Parameter Required Type Description
marketplace_order_id True String Order identifier of the marketplace
account_id True Integer Your account ID
marketplace True String The marketplace name
action_type True String Action type

Depending on marketplace and action, some parameters are conditional and need to be included or to have specific values. Please refer to the marketplace API.

Parameter Required Type Description
tracking_number Conditional String Tracking number
tracking_url Conditional String Tracking URL (if not tracking_number)
carrier Conditional String Carrier
line Conditional String Line ID for partial action

Marketplaces

Get marketplace informations

Simple call :

curl https://api.lengow.io/v3.0/marketplaces/

GET https://api.lengow.io/v3.0/marketplaces/

Marketplace code

All keys of the result are a Marketplace code used by others API. Always refers you to this API to get this code.

A Marketplace code is unique and must match this regexp : [a-Z0-9-_]

Filtering

With filtering :

curl https://api.lengow.io/v3.0/marketplaces/?account_id=1
curl https://api.lengow.io/v3.0/marketplaces/?marketplace=darty
curl https://api.lengow.io/v3.0/marketplaces/?marketplace=darty&account_id=1

You can use the optionnal account_id filter to only get your marketplaces, or marketplace to get only one marketplace information:

Filter Required Description
account_id No To filter your marketplaces
marketplace No To get only the specified marketplace information

Result

Result json :

{
    "name": "Boulanger",
    "logo": "http://blog.boulanger.fr/wp-content/uploads/2010/10/logo-boulsign.jpg",
    "legacy_code": "boulanger",
    "description": "Launched at the end of 2014, the household electronics expert Boulanger has a rich range of items, and welcomes niche products. With brick-and-mortar experience spanning over 50 years, Boulanger now offers its expertise to internet users, and its large assortment of SKUs promises a quality audience.",
    "country": "FRA",
    "homepage": "http://www.boulanger.com/",
    "orders": {
      "status": {
        "canceled": [
          "CANCELED"
        ],
        "closed": [
          "RECEIVED",
          "CLOSED"
        ],
        "refunded": [
          "REFUNDED"
        ],
        "accepted": [
          "WAITING_DEBIT",
          "WAITING_DEBIT_PAYMENT"
        ],
        "shipped": [
          "SHIPPED"
        ]
      },
      "carriers": {
        "DHL": {
          "label": "DHL"
        },
        "Chronopost": {
          "label": "Chronopost"
        }
      },
      "actions": {
        "ship": {
          "status": [
            "waiting_shipment"
          ],
          "optional_args": [
            "carrier",
            "carrier_name",
            "tracking_url"
          ],
          "args_description": {
            "tracking_url": {
              "accept_free_values": true,
              "depends_on": {
                "operator": "allOf",
                "conditions": [
                  {
                    "key_path": {
                      "root": "order",
                      "path": "order_meta.delivery_type",
                    },
                    "function": "equals",
                    "value": "PARCEL"
                  }
                ]
              }
            },
            "carrier_name": {
              "accept_free_values": true
            }
          },
          "args": [
            "tracking_number"
          ]
        },
        "accept": {
          "status": [
            "waiting_acceptance"
          ],
          "optional_args": [
            "line"
          ],
          "args_description": {},
          "args": []
        },
        "refuse": {
          "status": [
            "waiting_acceptance"
          ],
          "optional_args": [
            "line"
          ],
          "args_description": {},
          "args": []
        }
      }
    }
  }
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)
orders.status Object Mapping between lengow's status (keys) and marketplace's status (values)
orders.carriers Object All carriers available
orders.actions Object Informations about each actions (based on lengow's actions)

Detail of orders.actions

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 of the 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 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 particular case, we can see that both return_tracking_number and return_carrier have specific conditions.

return_tracking_number is a string field that accept 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

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 and our Amazon VCS guide for further information.

Retrieve VIDR data

Simple call:

GET https://api.lengow.io/v3.0/apps/amazon-vcs/vidr/?account_id=1&marketplace=amazon_de

This API allows you to retrieve VAT Invoice Data Report (VIDR) for invoices and credit notes.

Through this API you will have access to:

Good to know:

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

Filtering

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

You can filter the result with different filters. account_id and marketplace are mandatory filters.

List of supported fields:

Filter 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 proceed to 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 then need to use our Documents endpoint to upload it on Amazon.

Possible errors:

HTTP 400

Documents

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