--- title: Retrieve orders slug: merchant-api/retrieve-orders createdAt: 2021-07-13T13:47:11.000Z --- # Definition Retrieve your Marketplace orders from Neteven in order to integrate them into your system. # Endpoints ## Get new orders ### Endpoint definition | `GET` | `/merchant/orders/new` | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | returns orders **that are not yet completed** (shipped/canceled/refunded)
and not yet acknowledged as "*retrieved*" by the merchant. | | **Required scope** | `order_reader` | | **Pagination** | Please note that by default a maximum of
1000 orders will be displayed in a response. Please use parameters to
get results customized to your requirements. | | **Filtering** | only retrieve orders in status that is relevant to you. If you do not want to receive an order more than once, use the `PATCH` method to flag `order_lines` are retrieved. | | **Returns** | array of `order` objects, corresponding to the input parameters.
**NOTE:** orders acknowledged (via `PATCH`) will **never be returned**. | :::hint{type="info"} **Important: **an order will show in the response of the `GET` `/merchant/orders/new` if there is at least one of its `order_lines` is not considered as "retrieved" yet. The `order_lines` that are already *acknowledged* or already completed **will not be returned**, even if their corresponding order is. ::: **examples:** :::CodeblockTabs request ```curl curl --request GET \ --url 'https://api.neteven.com/v1/merchant/orders/new?limit=2&include_marketplace_fulfilled_orders=false&status=TO%20SHIP' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $MYTOKEN' \ --header 'Content-Type: application/json' ``` 200 OK response ```javascript { "data": { "orders": [ { "order_id": 7526300, "marketplace_order_id": "SANDBOX_7501319_002", "order_lines_count": 1, "date_creation": "2014-09-24T15:22:21", "date_sale": "2014-09-24T15:18:16", "date_payment": "2014-09-24T15:18:16", "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 3146.80, "total_price_excluding_taxes_excluding_shipping": 2622.33 }, "shipping_information": { "carrier_name": "TestWS1-1-Order001-TrackingInfo-7526358", "tracking_url": "TestWS1-1-Order001-TrackingURL-7526358", "tracking_number": "TestWS1-1-Order001-TrackingNumber-7526358" }, "address_delivery": { "title": "anonymized", "first_name": "anonymized", "last_name": "anonymized", "street1": "anonymized", "street2": "anonymized", "city": "anonymized", "country_code": "FR", "country": "FRANCE", "postcode": "95500", "phone1": "secret", "phone2": "anonymized", "fax": "anonymized", "email": "anonymized", "login": "anonymized", "company_name1": "anonymized", "company_name2": "anonymized", "delivery_relay_name": "anonymized", "delivery_relay_contractlevel": "anonymized", "delivery_relay_id": "anonymized" }, "address_invoice": { "title": "anonymized", "first_name": "anonymized", "last_name": "anonymized", "street1": "anonymized", "street2": "anonymized", "city": "anonymized", "country_code": "FR", "country": "FRANCE", "postcode": "95500", "phone1": "secret", "phone2": "anonymized", "fax": "anonymized", "email": "anonymized", "login": "anonymized", "company_name1": "anonymized", "company_name2": "anonymized" }, "order_lines": [ { "order_line_id": 9811700, "marketplace_order_line_id": "SANDBOX_7501319_3_002", "status_current": "TO SHIP", "item": { "sku": "HPOLBICNOINOI-M", "marketplace_product_id": "SANDBOX_PRODUCT_3029_HPOLBICNOINOI-M", "quantity": 1, "warehouse_name": "Aurel_warehouse" }, "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 77.69, "total_price_excluding_taxes_excluding_shipping": 64.74 } } ] }, { "order_id": 9549000, "marketplace_order_id": "SANDBOX_9549613", "order_lines_count": 2, "date_creation": "2015-07-23T09:54:54", "date_sale": "2015-07-23T09:56:00", "date_payment": "2015-07-23T09:56:00", "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 220.54, "total_price_excluding_taxes_excluding_shipping": 183.79 }, "shipping_information": { "carrier_name": "TestWS1-1-Order001-TrackingInfo-9549575", "tracking_url": "TestWS1-1-Order001-TrackingURL-9549575", "tracking_number": "TestWS1-1-Order001-TrackingNumber-9549575" }, "address_delivery": { "title": "anonymized", "first_name": "anonymized", "last_name": "anonymized", "street1": "anonymized", "street2": "anonymized", "city": "anonymized", "country_code": "FR", "country": "FRANCE", "postcode": "13127", "phone1": "secret", "phone2": "anonymized", "fax": "anonymized", "email": "anonymized", "login": "anonymized", "company_name1": "anonymized", "company_name2": "anonymized", "delivery_relay_name": "anonymized", "delivery_relay_contractlevel": "anonymized", "delivery_relay_id": "anonymized" }, "address_invoice": { "title": "anonymized", "first_name": "anonymized", "last_name": "anonymized", "street1": "anonymized", "street2": "anonymized", "city": "anonymized", "country_code": "FR", "country": "FRANCE", "postcode": "13127", "phone1": "secret", "phone2": "anonymized", "fax": "anonymized", "email": "anonymized", "login": "anonymized", "company_name1": "anonymized", "company_name2": "anonymized" }, "order_lines": [ { "order_line_id": 1168000, "marketplace_order_line_id": "SANDBOX_9549613_3", "status_current": "TO SHIP", "stock_released": true, "item": { "sku": "D6", "marketplace_product_id": "SANDBOX_PRODUCT_3029_D6", "quantity": 3, "warehouse_name": "Aurel_warehouse" }, "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 94.26, "total_price_excluding_taxes_excluding_shipping": 78.55 } }, { "order_line_id": 11689004, "marketplace_order_line_id": "SANDBOX_9549613_1", "status_current": "TO SHIP", "stock_released": true, "item": { "sku": "000002", "ean": "EAN", "marketplace_product_id": "SANDBOX_PRODUCT_3029_000002", "quantity": 2, "warehouse_name": "Aurel_warehouse" }, "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 63.44, "total_price_excluding_taxes_excluding_shipping": 52.87 } } ] } ] }, "metadata": { "number_of_results": 2, "api_version": 1, "api_version_expiration_date": "2022-12-31", "total_count": 76, "limit": 2, "offset": 0 } } ``` ::: ### Endpoint specific errors :::hint{type="success"} This endpoint should never return any error besides validation errors (misuse of query params). If no orders are available, the `data.orders` list in the response will simply be empty. ::: *** ## Get orders based on filters ### Endpoint definition | `GET` | `/merchant/orders` | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | returns orders based on filters. Unlike the `/merchant/orders/new` endpoint, this will return orders regardless of their *acknowledgement* status.

Limit the use of this method for very specific use cases: always use the `/merchant/orders/new` endpoint over this one when possible. | | **Required scope** | `order_reader` | | **Pagination** | Please note that by default a maximum of
1000 orders will be displayed in a response. Please use parameters to
get results customized to your requirements. | | **Filtering** | Combine filters to get the relevant information only.
**NOTE:** orders older than 90 days will not be returned. | | **Returns** | array of `order` objects, corresponding to the input parameters. | **Example:** :::CodeblockTabs Get orders ```curl curl --request GET \ --url 'https://api.neteven.com/v1/merchant/orders?limit=2&status=TO%20SHIP' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $MYTOKEN' \ --header 'Content-Type: application/json' ``` 200 OK Response ```javascript { "data": { "orders": [ { "order_id": 7526300, "marketplace_order_id": "SANDBOX_7501319_002", "order_lines_count": 1, "date_creation": "2014-09-24T15:22:21", "date_sale": "2014-09-24T15:18:16", "date_payment": "2014-09-24T15:18:16", "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 3146.80, "total_price_excluding_taxes_excluding_shipping": 2622.33 }, "shipping_information": { "carrier_name": "TestWS1-1-Order001-TrackingInfo-7526358", "tracking_url": "TestWS1-1-Order001-TrackingURL-7526358", "tracking_number": "TestWS1-1-Order001-TrackingNumber-7526358" }, "address_delivery": { "title": "anonymized", "first_name": "anonymized", "last_name": "anonymized", "street1": "anonymized", "street2": "anonymized", "city": "anonymized", "country_code": "FR", "country": "FRANCE", "postcode": "95500", "phone1": "secret", "phone2": "anonymized", "fax": "anonymized", "email": "anonymized", "login": "anonymized", "company_name1": "anonymized", "company_name2": "anonymized", "delivery_relay_name": "anonymized", "delivery_relay_contractlevel": "anonymized", "delivery_relay_id": "anonymized" }, "address_invoice": { "title": "anonymized", "first_name": "anonymized", "last_name": "anonymized", "street1": "anonymized", "street2": "anonymized", "city": "anonymized", "country_code": "FR", "country": "FRANCE", "postcode": "95500", "phone1": "secret", "phone2": "anonymized", "fax": "anonymized", "email": "anonymized", "login": "anonymized", "company_name1": "anonymized", "company_name2": "anonymized" }, "order_lines": [ { "order_line_id": 9811700, "marketplace_order_line_id": "SANDBOX_7501319_3_002", "status_current": "TO SHIP", "item": { "sku": "HPOLBICNOINOI-M", "marketplace_product_id": "SANDBOX_PRODUCT_3029_HPOLBICNOINOI-M", "quantity": 1, "warehouse_name": "Aurel_warehouse" }, "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 77.69, "total_price_excluding_taxes_excluding_shipping": 64.74 } } ] }, { "order_id": 9549000, "marketplace_order_id": "SANDBOX_9549613", "order_lines_count": 2, "date_creation": "2015-07-23T09:54:54", "date_sale": "2015-07-23T09:56:00", "date_payment": "2015-07-23T09:56:00", "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 220.54, "total_price_excluding_taxes_excluding_shipping": 183.79 }, "shipping_information": { "carrier_name": "TestWS1-1-Order001-TrackingInfo-9549575", "tracking_url": "TestWS1-1-Order001-TrackingURL-9549575", "tracking_number": "TestWS1-1-Order001-TrackingNumber-9549575" }, "address_delivery": { "title": "anonymized", "first_name": "anonymized", "last_name": "anonymized", "street1": "anonymized", "street2": "anonymized", "city": "anonymized", "country_code": "FR", "country": "FRANCE", "postcode": "13127", "phone1": "secret", "phone2": "anonymized", "fax": "anonymized", "email": "anonymized", "login": "anonymized", "company_name1": "anonymized", "company_name2": "anonymized", "delivery_relay_name": "anonymized", "delivery_relay_contractlevel": "anonymized", "delivery_relay_id": "anonymized" }, "address_invoice": { "title": "anonymized", "first_name": "anonymized", "last_name": "anonymized", "street1": "anonymized", "street2": "anonymized", "city": "anonymized", "country_code": "FR", "country": "FRANCE", "postcode": "13127", "phone1": "secret", "phone2": "anonymized", "fax": "anonymized", "email": "anonymized", "login": "anonymized", "company_name1": "anonymized", "company_name2": "anonymized" }, "order_lines": [ { "order_line_id": 1168000, "marketplace_order_line_id": "SANDBOX_9549613_3", "status_current": "TO SHIP", "stock_released": true, "item": { "sku": "D6", "marketplace_product_id": "SANDBOX_PRODUCT_3029_D6", "quantity": 3, "warehouse_name": "Aurel_warehouse" }, "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 94.26, "total_price_excluding_taxes_excluding_shipping": 78.55 } }, { "order_line_id": 11689004, "marketplace_order_line_id": "SANDBOX_9549613_1", "status_current": "TO SHIP", "stock_released": true, "item": { "sku": "000002", "ean": "EAN", "marketplace_product_id": "SANDBOX_PRODUCT_3029_000002", "quantity": 2, "warehouse_name": "Aurel_warehouse" }, "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 63.44, "total_price_excluding_taxes_excluding_shipping": 52.87 } } ] } ] }, "metadata": { "number_of_results": 2, "api_version": 1, "api_version_expiration_date": "2022-12-31", "total_count": 76, "limit": 2, "offset": 0 } } ``` ::: ### Endpoint specific errors :::hint{type="success"} This endpoint should never return any error besides validation errors (misuse of query params). If no orders are available, the `data.orders` list in the response will simply be empty. ::: *** ## Get a single order ### Endpoint definition | `GET` | `/merchant/orders/{order-id}` | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | returns a single order object. Useful for ad hoc verifications on a specific order. This is mostly useless in a standard order management integration workflow. | | **Required scope** | `order_reader` | | **Path parameter** | **- *`order-id`***: Neteven identifier for the order object | | **Returns** | one single `order` object, including every `order_lines`, regardless of their status. | **Example:** :::CodeblockTabs ```curl curl --request GET \ --url 'https://api.neteven.com/v1/merchant/orders/7526300' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $MYTOKEN' \ --header 'Content-Type: application/json' ``` 200 OK response ```javascript { "data": { "order": { "order_id": 7526300, "marketplace_order_id": "SANDBOX_0000_002", "order_lines_count": 3, "date_creation": "2014-09-24T15:22:21", "date_sale": "2014-09-24T15:18:16", "date_payment": "2014-09-24T15:18:16", "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 3146.80, "total_price_excluding_taxes_excluding_shipping": 2622.33 }, "shipping_information": { "carrier_name": "TestWS1-1-Order001-TrackingInfo-7526358", "tracking_url": "TestWS1-1-Order001-TrackingURL-7526358", "tracking_number": "TestWS1-1-Order001-TrackingNumber-7526358" }, "address_delivery": { "title": "anonymized", "first_name": "anonymized", "last_name": "anonymized", "street1": "anonymized", "street2": "anonymized", "city": "anonymized", "country_code": "FR", "country": "FRANCE", "postcode": "95500", "phone1": "secret", "phone2": "anonymized", "fax": "anonymized", "email": "anonymized", "login": "anonymized", "company_name1": "anonymized", "company_name2": "anonymized", "delivery_relay_name": "anonymized", "delivery_relay_contractlevel": "anonymized", "delivery_relay_id": "anonymized" }, "address_invoice": { "title": "anonymized", "first_name": "anonymized", "last_name": "anonymized", "street1": "anonymized", "street2": "anonymized", "city": "anonymized", "country_code": "FR", "country": "FRANCE", "postcode": "95500", "phone1": "secret", "phone2": "anonymized", "fax": "anonymized", "email": "anonymized", "login": "anonymized", "company_name1": "anonymized", "company_name2": "anonymized" }, "order_lines": [ { "order_line_id": 9811600, "marketplace_order_line_id": "SANDBOX_7501319_1_002", "status_current": "TO CONFIRM", "item": { "sku": "HCAPLEONOI-TU", "ean": "3606852811431", "marketplace_product_id": "SANDBOX_PRODUCT_3029_HCAPLEONOI-TU", "quantity": 1 }, "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 190.31, "total_price_excluding_taxes_excluding_shipping": 158.59 } }, { "order_line_id": 9811700, "marketplace_order_line_id": "SANDBOX_7501319_3_002", "status_current": "TO SHIP", "item": { "sku": "HPOLBICNOINOI-M", "marketplace_product_id": "SANDBOX_PRODUCT_3029_HPOLBICNOINOI-M", "quantity": 1, "warehouse_name": "Aurel_warehouse" }, "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 77.69, "total_price_excluding_taxes_excluding_shipping": 64.74 } }, { "order_line_id": 9811000, "marketplace_order_line_id": "SANDBOX_7501319_2_002", "status_current": "TO CONFIRM", "item": { "sku": "69023-AAM-GHTP", "ean": "3231760424042", "marketplace_product_id": "SANDBOX_PRODUCT_3029_69023-AAM-GHTP", "quantity": 3 }, "prices": { "currency_id": "EUR", "total_price_including_taxes_excluding_shipping": 2878.80, "total_price_excluding_taxes_excluding_shipping": 2399.00 } } ] } }, "metadata": { "number_of_results": 1, "api_version": 1, "api_version_expiration_date": "2022-12-31" } } ``` ::: ### Endpoint specific errors **Response HTTP Header code :** `404` **Cause:** The order id submitted was not recognized (it doesn't exist on your account). **Actionable :** Ensure that the order\_id sent as a path parameter is correct. Order id can be retrieved using the `get /merchant/orders` or `get /merchant/orders/new` endpoints. Do NOT retry the same call without verifying the validity of the `order-id` used as a path parameter. :::hint{type="success"} It is very unlikely that you will encounter this error during the production phase, since you are retrieving the `order-id` to use as a path parameter from a `GET /merchant/orders` endpoint. ::: **Example:** :::BlockQuote \{ "message": "order {order-id} not recognized", "code": 404, "title": "Not Found } ::: *** # API reference *more information on parameters, responses and content in the *[API Reference](docId\:yWeBKEf7Kqp3agiK6LtoJ)