Retrieve orders

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.

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:

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'

Endpoint specific errors

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:

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'

Endpoint specific errors

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:

{
  "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.

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:

{ "message": "order {order-id} not recognized", "code": 404, "title": "Not Found }

API reference

more information on parameters, responses and content in the API Reference