Guides
Start typing to search…

Retrieve a List of Orders

Overview

This guide shows how to retrieve a list of orders from the ShipMonk API using the GET /v1/orders endpoint.

Prerequisites

Endpoint Details

GET https://api.shipmonk.com/v1/orders

Authentication

Include your API key in the request header:

 --header 'Api-Key: YOUR_API_KEY'

Query Parameters

ParameterTypeRequiredDefaultDescription
searchstringNo-Search term to filter orders
pageintegerNo1Page number (must be > 0)
pageSizeintegerNo50Number of items per page (max: 500)
sortBystringNo"id"Field to sort by
sortOrderstringNo"ASC"Sort order: "ASC" or "DESC"
statusstringNo-Filter by order status
dateCreatedStartdate-timeNo-Filter by creation date (start)
dateCreatedEnddate-timeNo-Filter by creation date (end)
dateUpdatedStartdate-timeNo-Filter by update date (start)
dateUpdatedEnddate-timeNo-Filter by update date (end)

For additional definitions and terminology, review our API field definitions here.

Example Request

curl --request GET \
  --url 'https://api.shipmonk.com/v1/orders?page=1&pageSize=50&sortOrder=ASC' \
  --header 'Api-Key: YOUR_API_KEY'
import requests

url = "https://api.shipmonk.com/v1/orders"
headers = {"Api-Key": "YOUR_API_KEY"}
params = {"page": 1, "pageSize": 50}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)
const options = {
  method: 'GET',
  headers: {'Api-Key': 'YOUR_API_KEY'}
};

fetch('https://api.shipmonk.com/v1/orders?page=1&pageSize=50', options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

Response Format

{
  "status": 0,
  "data": {
    "orders": [
      {
        "order_key": "string",
        "order_number": "string",
        "store": {
          "id": 0,
          "name": "string"
        },
        "ordered_at": "2025-10-20T13:40:56.321Z",
        "customer_email": "string",
        "ship_from": {
          "name": "string",
          "company": "string",
          "street1": "string",
          "street2": "string",
          "state": "string",
          "city": "string",
          "zip": "string",
          "country_code": "string",
          "phone": "string",
          "email": "string",
          "residential": true
        },
        "ship_to": {
          "name": "string",
          "company": "string",
          "street1": "string",
          "street2": "string",
          "state": "string",
          "city": "string",
          "zip": "string",
          "country_code": "string",
          "phone": "string",
          "email": "string",
          "residential": true
        },
        "order_status": "unfulfilled",
        "processing_status": "backorder",
        "currency_code": "string",
        "items": [
          {
            "line_key": "string",
            "sku": "string",
            "name": "string",
            "quantity": 0,
            "price": 0,
            "image_url": "string",
            "fulfilled_quantity": 0,
            "source": "imported",
            "products": [
              {
                "sku": "string",
                "quantity": 0,
                "lot": {
                  "number": "string",
                  "expiration_date": "2025-10-20"
                }
              }
            ]
          }
        ],
        "actions_required": {
          "item_mapping": true,
          "address": true,
          "shipping_mapping": true,
          "customs": true,
          "at_risk": true,
          "routing": true,
          "freight_quote": true,
          "freight_info": true,
          "ship_short": true,
          "hs_code": true,
          "global_e_label": true,
          "ship_monk_hazmat_carrier_service_not_available": true,
          "automation_rule": true
        },
        "packages": [
          {
            "number": 0,
            "tracking_number": "string",
            "tracking_url": "string",
            "weight_lb": {
              "value": 0,
              "unit": "kg"
            },
            "pallet_weight_lb": {
              "value": 0,
              "unit": "kg"
            },
            "box_number": 0,
            "pallet_number": 0
          }
        ],
        "tracking_url": "string",
        "requested_shipping_service": "string",
        "shipping_method": {
          "id": 0,
          "name": "string",
          "carrier": {
            "id": 0,
            "name": "string"
          }
        },
        "master_tracking_number": "string",
        "shipment_data": {
          "carrier": "string",
          "service": "string",
          "carrier_tracking_url": "string",
          "carrier_alpha_code": "string",
          "carrier_trans_method_code": "string",
          "bill_of_lading_number": "string",
          "master_bill_of_lading_number": "string",
          "load_number": "string",
          "authorization_number": "string",
          "estimated_shipping_cost": 0,
          "routing": {
            "routing_key": "string"
          }
        },
        "shipped_at": "2025-10-20T13:40:56.321Z",
        "order_size": "unknown",
        "serial_numbers": [
          {
            "line_key": "string",
            "serial_numbers": [
              {
                "sku": "string",
                "serial_number": "string"
              }
            ]
          }
        ],
        "gift_message": "string",
        "gift_from": "string",
        "customer_notes": "string",
        "order_detail_url": "string"
      }
    ]
  }
}

Response Fields

  • data: Array of order objects
  • total: Total number of orders matching the query
  • pages: Total number of pages available
  • page: Current page number

Steps to Retrieve Orders

  1. Obtain your API key

  2. Construct the request

    • Set the base URL:
      • Production: https://api.shipmonk.com/v1/orders
      • Sandbox: https://sandbox.shipmonk.com/v1/orders
    • Add query parameters as needed (pagination, filters, sorting)
    • Include the Api-Key header with your API key

  3. Make the GET request

    • Send the request to the endpoint
    • Wait for the response

  4. Parse the response

    • Check for successful status code (200)
    • Extract the data array containing orders
    • Note pagination info: total, pages, page

  5. Handle pagination (if needed)

    • Check if pages > page
    • Make additional requests with incremented page parameter
    • Continue until all pages are retrieved

  6. Error handling

    • Catch network errors
    • Handle authentication failures (401)
    • Handle rate limiting (429)
    • Validate response structure

Common Queries

Get orders by status

curl --request GET \
     --url 'https://sandbox.shipmonk.dev/v1/orders?status=pending&pageSize=500' \
     --header 'Api-Key: YOUR_API_KEY' \
     --header 'accept: application/json'

Search for specific orders

curl --request GET \
     --url 'https://sandbox.shipmonk.dev/v1/orders?search=search_term&pageSize=50' \
     --header 'Api-Key: YOUR_API_KEY' \
     --header 'accept: application/json'

Get recently updated orders

curl --request GET \
     --url 'https://sandbox.shipmonk.dev/v1/orders?dateUpdatedStart=2025-01-01T00:00:00Z&sortBy=dateUpdated&sortOrder=DESC' \
     --header 'Api-Key: YOUR_API_KEY' \
     --header 'accept: application/json'

Retrieve a List of Orders

Overview

This guide shows how to retrieve a list of orders from the ShipMonk API using the GET /v1/orders endpoint.

Prerequisites

Endpoint Details

GET https://api.shipmonk.com/v1/orders

Updated 1 day ago