Order dev guide

Recommended integration flow

The Order API offers several different ways of retrieving new orders via its endpoints. The most obvious one is GET /merchant/orders/new. This endpoint has been designed specifically to provide an easy-to-use entry point to retrieving marketplace orders.

Below, a suggestion of basic workflow to retrieve orders via the API.

step 1 - Set up your request

Add query parameters:

if you let Neteven manage the automatic order validation/cancelation, add the status=TO SHIP query parameter

if you have activated Marketplace fulfillment features, you can chose to exclude these orders with the include_marketplace_fulfilled_orders=false query parameter (default value)

only use the marketplace_ids query parameter if you need a separate integration process per marketplace

Call the endpoint:

curl --request GET \
  --url 'https://api.neteven.com/v1/merchant/orders/new?limit=50&include_marketplace_fulfilled_orders=false&status=TO%20SHIP' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $MYTOKEN' \
  --header 'Content-Type: application/json'

step 2 - Parse the response body

in the response body, you will be able to know how many order objects correspond to your query by looking into the reponse.metadata.total_count attribute.

If that count exceeds your limit, you can call repeatedly, using the offset query parameter to browse through the results until you recuperated them all (or simply update order items and query again until you no longer have results).

Integrate orders and order items into your system

step 3 - acknowledge received orders

Acknowledging orders does not send messages to marketplaces or customer, but simply allows the Neteven API to know that these orders no longer need to be included in the GET /merchant/orders/new response.

For each individual order_line, send a PATCH /orders/lines/ack request including its corresponding merchant_order_line_id

If you do not have an internal identifier for order items, you can send any other value as the merchant_order_line_id (example: sending the neteven order_line_id)

example on order_line_id 98811700:

curl --request PATCH \
  --url https://api.neteven.com/v1/merchant/orders/7526300/lines/9811700/ack \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $MYTOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "merchant_order_line_id": "MyOwnID_for_9811700"
}'

{
  "data": {
    "order_line": {
      "order_line_id": 9811700,
      "status": {
        "message": "merchant_order_line_id MyOwnID_for_9811700 inserted",
        "code": 200,
        "title": "OK"
      }
    }
  },
  "metadata": {
    "api_version": 1,
    "api_version_expiration_date": "2022-12-31",
    "number_of_results": 1
  }
}

The above response shows that order_line_id: 9811700has been acknowledged. It will no longer show in the response of the GET /merchant/orders/new response.

repeat this process until every order line is properly integrated into your system and acknowledged.

step 4 - update order line statuses

Once orders are processed on your side, you might want to confirm / cancel / ship or refund specific items.

Since every Marketplace has its own restrictions in terms of order management workflow, you should design your integration with the order API in a way that allows for specific changes based on the Marketplace of origin.

loop through open order lines on your side and send confirm / cancel / ship / refund status update requests.

After a certain amount of time (usually 15 to 30 minutes), you can interrogate the API to get the status of the request, and have the final confirmation of the successful (or failed) attempt to update the order line status.

Below is an example of PATCH /merchant/orders/lines/ship on a given order_line_id 98811700:

curl --request PATCH \
  --url https://api.neteven.com/merchant/orders/7526300/lines/9811600/ship \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $MYTOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "shipping_information": {"date_shipping": "2021-01-01T12:12:12", "tracking_number": "XYZ123"}
}'

{
  "data": {
    "order_line": {
      "order_line_id": 9811699,
      "status": {
        "message": "Accepted",
        "code": 202,
        "title": "OK"
      }
    }
  },
  "metadata": {
    "api_version": 1,
    "api_version_expiration_date": "2022-12-31",
    "number_of_results": 1
  }
}

Note that every status update is actually an asynchroneous process, which is notified by the 202 Accepted HTTP status code: the API confirms that the status update request was properly registered, but Neteven needs to pass it on to the actual Marketplace via downstream systems before it can confirm the request was successful.

After waiting a while, you can call the GET /merchant/orders/lines/status endpoint to check if your request was accepted by the Marketplace:

curl --request GET \
  --url https://api.neteven.com/merchant/orders/7526300/lines/9811600/status \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $MYTOKEN' \
  --header 'Content-Type: application/json'

{
  "data": {
    "order_line_status": {
      "order_line_id": 9811600,
      "marketplace_order_line_id": "SANDBOX_7501319_1_002",
      "merchant_order_line_id": "MyOwnID_for_9811700",
      "sku": "HCAPLEONOI-TU",
      "ean": "3606852811400",
      "status_current": "TO SHIP",  // the last valid status received by the Marketplace
      "status_request": {
        "action_id": 618624727,
        "action_label": "SHIPPING CONFIRMATION REQUEST",
        "date_start": "2021-10-06T18:46:17",
        "date_end": "2021-10-06T19:00:11",
        "state": "PENDING",  //The action is not yet over
        "message": ""
      }
    }
  },
  "metadata": {
    "number_of_results": 1,
    "api_version": 1,
    "api_version_expiration_date": "2022-12-31"
  }
}

The data.order_line_status.status_current attribute shows the last valid status on that specific order line. It is different from the desired status SHIPPED because the status change request has yet to be accepted by the marketplace.

The status_request bloc in the response shows that the action is still PENDING, which means that Neteven is awaiting confirmation from the Marketplace system that the request was accepted.

In this instance, you should wait some time and call again until data.order_line_status.status_request.state is equal to SUCCESS or FAILED.

If the action failed, you can have more information in the message attribute.

If the state ends in SUCCESS, you can consider the action done, and in this instance the order_line as SHIPPED. The status_current value will be update to its new status.

For most order items, the cycle ends here. In some instances, you might have to send a refund status request if there was a customer return.

Getting Marketplace fulfilled orders

In some instances, you might want to filter in/out orders fulfilled by Marketplaces. Please find below some use case and how to solve them:

I want to retrieve ZFS orders (fulfilled by Zalando) regardless of their status and regardless of whether I have already retrieved them. -> You want to use the GET /orders and use the fulfilment_type filter combined with the list of marketplace_ids corresponding to Zalando Marketplaces -> GET /orders?fulfillment_type=FulfilledByMarketplace&marketplace_ids=37,47,...

I only want to retrieve orders that I have already shipped myself -> You want to use the GET /orders and use the fulfilment_type filter combined with the status filter as "SHIPPED" -> GET /orders?fulfillment_type=FulfilledByMerchant&status=SHIPPED

I want to retrieve FBA (fulfilled by Amazon) orders only once and already shipped -> If you do not want to retrieve the same orders many time, you can still use the GET /orders, combining several filters : fulfilment_type , marketplace_ids (with Amazon marketplace ids), the status as "SHIPPED" and the acknowledged filter as false -> GET /orders?fulfillment_type=FulfilledByMarketplace&status=SHIPPED&acknowledged=false&marketplace_ids=7,58,29 -> then do a PATCH /order/line/ack on the order_lines included in the response body.

I want to exclude marketplace fulfilled orders from the new orders I fetch -> You can call the standard call with the added parameter to filter out the marketplace fulfilled_orders. GET /orders/new?fulfillment_type=FulfilledByMerchant

Important things to keep in mind

Important: Note that the order API works at the lowest level which is the order_line. That means that if you want to update an entire order as shipped, you must update every one of its order_lines as such via the PATCH /merchant/orders/lines/ship method.

This design choice was made to ensure a uniform workflow across all Marketplace orders.

Although the Merchant API is build with a standardized structure regardless of the channel your account is live on, there might still be Marketplace specific workflows and content within the order management process.

You should design your integration with the Neteven API in a way that limits the unnecessary or redundant requests to the API. For example, there is no need to check the state of an order_line status change request every minute considering that the average time for the whole process (from Neteven to Marketplace including response) is usually 30 to 60 minutes long.