--- title: Order dev guide slug: merchant-api/order-dev-guide createdAt: 2021-10-06T14:50:58.000Z --- # 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:** :::CodeblockTabs Get new orders ```curl 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***:** :::CodeblockTabs acknowledge order line ```curl 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" }' ``` ::: :::CodeblockTabs reponse ```javascript { "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: 9811700`has 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. :::hint{type="info"} 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 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"} }' ``` :::CodeblockTabs response ```javascript { "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: :::CodeblockTabs check order line status request ```curl 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' ``` ::: :::CodeblockTabs response ```javascript { "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: 1. ***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,...` 2. ***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` 3. ***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. 4. ***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 :::hint{type="success"} **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. ::: :::hint{type="success"} 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. ::: :::hint{type="info"} 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. :::