Retrieve orders by criteria

POST /order/find/

Finds orders based on specified criteria, such as channel, account token, and various filters like sale date, status, and buyer details.

Query parameters

channel string Required

The name of the sales channel (e.g., eBay, Amazon).

Values are ebay, amazon, walmart, kaufland, or tiktok.
account_token string(uuid) Required

A unique token identifying the account on the specified sales channel.

application/json

Body

Criteria for filtering and sorting orders.

sort object

Sorting options for the search results.

Additional properties are allowed.
Hide sort attributes Show sort attributes object
- sale_date string
  
  Order by sale date.
  
  Values are asc or desc.
- ship_by_date string
  
  Order by ship by date.
  
  Values are asc or desc.
- status string
  
  Order by order status.
  
  Values are asc or desc.
- order_total string
  
  Order by order total.
  
  Values are asc or desc.
filters object

Filtering options.

Additional properties are allowed.
Hide filters attributes Show filters attributes object
- archived array[boolean]
  
  Filter by archived: yes|no
  
  At least 1 but not more than 1 element.
- buyer array[string]
  
  Filter by Buyer firstName or lastName
  
  At least 1 but not more than 1 element.
- data_source_order array[string]
  
  Filter by created in store: yes|no
  
  At least 1 but not more than 1 element.
- price object
  
  Filter by total price range.
  
  Additional properties are allowed.
  Hide price attributes Show price attributes object
  
  from number
  
  to number
- shipping_price object
  
  Filter by shipping price range.
  
  Additional properties are allowed.
  Hide shipping_price attributes Show shipping_price attributes object
  
  from number
  
  to number
- status array[integer]
  
  Order statuses (e.g., 1 = Pending, 2 = Unshipped, 3 = Partially Shipped, 4: Completed, 5: Cancelled, 9: Refunded).
  
  Values are 1, 2, 3, 4, 5, or 9.
- sale_date object
  
  Filter orders by sale date range.
  
  Additional properties are allowed.
  Hide sale_date attributes Show sale_date attributes object
  
  from string(date-time)
  
  to string(date-time)
- ship_by_date object
  
  Filter orders by ship by date range.
  
  Additional properties are allowed.
  Hide ship_by_date attributes Show ship_by_date attributes object
  
  from string(date-time)
  
  to string(date-time)
search string | null

Search by Title, SKU, Identifier, GTIN
_result object

Additional properties are allowed.
Hide _result attribute Show _result attribute object
- limit object Required
  
  Additional properties are allowed.
  Hide limit attributes Show limit attributes object
  
  offset integer Required
  
  Minimum value is 0.
  
  count integer Required
  
  Minimum value is 1, maximum value is 100.

Responses

200 application/json

Orders retrieved successfully.
Hide headers attributes Show headers attributes
- X-RateLimit-Limit number
  
  The number of allowed requests in the current period.
- X-RateLimit-Remaining number
  
  The number of remaining requests in the current period.
- X-RateLimit-Retry-After string(datetime)
  
  The date of number of remaining requests will reset.
Hide response attributes Show response attributes object
- list array[object] Required
  
  A list of orders matching the query.
  
  Represents an order with details about the buyer, status, dates, shipping, total cost, and items purchased.
  
  Hide list attributes Show list attributes object
  
  token string(uuid) Required
  
  A unique token associated with the order.
  
  order_id string Required
  
  The order ID assigned by the sales channel.
  
  source_order_id string Required
  
  The store-specific order ID, often used internally.
  
  buyer_name string | null Required
  
  Name of the buyer who placed the order.
  
  buyer_email string | null Required
  
  Email address of the buyer.
  
  status string Required
  
  Current status of the order.
  
  Values are pending, unshipped, partially_shipped, completed, cancelled, unshipped_partially_refunded, partially_shipped_partially_refunded, completed_partially_refunded, or refunded.
  
  is_archived boolean Required
  
  Indicates whether the order is archived.
  
  sale_date string(date-time) Required
  
  The date and time when the order was placed.
  
  ship_date string | null Required
  
  The actual shipping date of the order, if available.
  
  ship_by_date string | null Required
  
  The date by which the order should be shipped.
  
  shipping_address object Required
  
  Shipping address details for the order.
  
  Additional properties are allowed.
  
  Hide shipping_address attributes Show shipping_address attributes object
  
  name string | null Required
  
  Recipient's name for the shipping address.
  
  phone string | null Required
  
  Contact phone number for the recipient.
  
  street_first string | null Required
  
  Primary address line.
  
  street_second string | null Required
  
  Secondary address line (e.g., apartment, suite, PO box).
  
  city string | null Required
  
  City for the shipping address.
  
  state string | null Required
  
  State or province for the shipping address.
  
  postal_code string | null Required
  
  Postal or ZIP code.
  
  country_code string | null Required
  
  ISO 3166-1 alpha-2 country code.
  
  country_code string Required
  
  ISO 3166-1 alpha-2 country code representing the shipping country.
  
  Minimum length is 2, maximum length is 2.
  
  total object Required
  
  Total cost breakdown for the order.
  
  Additional properties are allowed.
  
  Hide total attributes Show total attributes object
  
  total number Required
  
  Total order cost, including all fees and discounts.
  
  shipping number Required
  
  Shipping cost for the order.
  
  subtotal number Required
  
  Subtotal cost of items before tax and discounts.
  
  tax number Required
  
  Total tax applied to the order.
  
  discount number Required
  
  Total discount applied to the order.
  
  currency string Required
  
  Currency code (ISO 4217 format) used in the order.
  
  items array[object] Required
  
  List of items included in the order.
  
  Represents an individual item within an order, including details such as SKU, quantity, and tracking information.
  
  Hide items attributes Show items attributes object
  
  title string Required
  
  The title or name of the item as it appears in the order.
  
  sku string Required
  
  Stock Keeping Unit (SKU) of the item.
  
  barcode string Required
  
  The barcode or UPC of the item.
  
  item_id string Required
  
  Unique identifier for the item.
  
  quantity integer Required
  
  The quantity of this item ordered.
  
  Minimum value is 1.
  
  price number(float) Required
  
  The unit price of the item.
  
  tracking_service string | null Required
  
  The name of the tracking service.
  
  tracking_numbers array[string] Required
  
  List of tracking numbers associated with this item.
- total integer Required
  
  The total number of orders matching the query.
400 application/json

Bad request
Hide headers attributes Show headers attributes
- X-RateLimit-Limit number
  
  The number of allowed requests in the current period.
- X-RateLimit-Remaining number
  
  The number of remaining requests in the current period.
- X-RateLimit-Retry-After string(datetime)
  
  The date of number of remaining requests will reset.
Hide response attributes Show response attributes object
- code string Required
  
  An error code that identifies the type of error that occurred.
- message string Required
  
  A message that describes the error condition in a human-readable form.
- data object | array Required
  
  Additional information that can help the caller understand or fix the issue.
404 application/json

Not found
Hide response attributes Show response attributes object
- code string Required
  
  An error code that identifies the type of error that occurred.
- message string Required
  
  A message that describes the error condition in a human-readable form.
- data object | array Required
  
  Additional information that can help the caller understand or fix the issue.
401 application/json

Unauthorized
Hide response attributes Show response attributes object
- code string Required
  
  An error code that identifies the type of error that occurred.
- message string Required
  
  A message that describes the error condition in a human-readable form.
- data object | array Required
  
  Additional information that can help the caller understand or fix the issue.
429 application/json

Too many requests
Hide headers attributes Show headers attributes
- X-RateLimit-Limit number
  
  The number of allowed requests in the current period.
- X-RateLimit-Remaining number
  
  The number of remaining requests in the current period.
- X-RateLimit-Retry-After string(datetime)
  
  The date of number of remaining requests will reset.
Hide response attributes Show response attributes object
- code string Required
  
  An error code that identifies the type of error that occurred.
- message string Required
  
  A message that describes the error condition in a human-readable form.
- data object | array Required
  
  Additional information that can help the caller understand or fix the issue.
500 application/json

Internal server error
Hide response attributes Show response attributes object
- code string Required
  
  An error code that identifies the type of error that occurred.
- message string Required
  
  A message that describes the error condition in a human-readable form.
- data object | array Required
  
  Additional information that can help the caller understand or fix the issue.

POST /order/find/

curl \
 --request POST https://m2e.cloud/api/v1/api/order/find/?channel=ebay&account_token=string \
 --header "Content-Type: application/json" \
 --data '{"sort":{"sale_date":"desc"},"_result":{"limit":{"count":10,"offset":0}},"filters":{"status":[1],"sale_date":{"from":"2020-12-01T15:30:50Z"}}}'

Request example

{
  "sort": {
    "sale_date": "desc"
  },
  "_result": {
    "limit": {
      "count": 10,
      "offset": 0
    }
  },
  "filters": {
    "status": [
      1
    ],
    "sale_date": {
      "from": "2020-12-01T15:30:50Z"
    }
  }
}

Response examples (200)

# Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 90
X-RateLimit-Retry-After: 2022-11-04T13:43:28Z

# Payload
{
  "list": [
    {
      "token": "1529970e-7508-489f-8a79-281225ee330e",
      "order_id": "113-00010001-0002002",
      "source_order_id": "0002002",
      "buyer_name": "Nadine Beebis",
      "buyer_email": "nbeebis0@eventbrite.com",
      "status": "completed",
      "is_archived": false,
      "sale_date": "2020-12-30T15:30:50Z",
      "ship_date": "2020-12-31T10:20:00Z",
      "ship_by_date": "2020-12-30T15:30:50Z",
      "shipping_address": {
        "name": "Nadine Beebis",
        "phone": "318-395-7232",
        "street_first": "7 Summerview Center",
        "street_second": "PO Box 29079",
        "city": "Sixi",
        "state": "NY",
        "postal_code": "976800",
        "country_code": "US"
      },
      "country_code": "US",
      "total": {
        "total": 44.55,
        "shipping": 5.55,
        "subtotal": 40.0,
        "tax": 0.55,
        "discount": 1.0,
        "currency": "USD"
      },
      "items": [
        {
          "title": "Wireless Bluetooth Headphones",
          "sku": "WBH-12345",
          "barcode": "012345678905",
          "item_id": "item-5678",
          "quantity": 2,
          "price": 59.99,
          "tracking_service": "UPS Ground",
          "tracking_numbers": [
            "1Z9999999999999999"
          ]
        }
      ]
    }
  ],
  "total": 1
}

Response examples (400)

[
  {
    "code": null,
    "message": "All array items must match schema"
  },
  {
    "code": null,
    "message": "The required properties (currency) are missing"
  }
]

Response examples (404)

[
  {
    "code": 404,
    "message": "Entity is not found."
  }
]

Response examples (401)

[
  {
    "code": 401,
    "message": "Unauthorized"
  }
]

Response examples (429)

[
  {
    "code": 429,
    "message": "Too many requests."
  }
]

Response examples (500)

[
  {
    "code": 500,
    "message": "Internal server error."
  }
]