Skip to main content
GET
/
v2
/
orders
List Orders
curl --request GET \
  --url https://api.puppetvendors.com/v2/orders \
  --header 'x-access-token: <api-key>'
V2 Alpha — This endpoint is part of the V2 API preview. Breaking changes may occur.

​
Overview

Retrieve a paginated list of orders. Vendor tokens are automatically scoped to orders containing their line items. Merchant tokens can optionally filter by vendor.

​
Use Cases

  • Sync orders to an external OMS, ERP, or accounting tool
  • Build dashboards showing recent order activity
  • Monitor vendor orders with vendor-scoped tokens

​
Query Parameters

​
vendorId
string
Filter by vendor ObjectId. Vendor tokens are auto-scoped and cannot override this.
​
locationId
integer
Filter by Shopify location ID.
​
status
string
Filter by status. One of: pending, partial, fulfilled, onHold, error, cancelled.
​
fulfillmentStatus
string
Filter by fulfillment status. One of: pending, success, error, onHold.
​
startDate
string
Filter by date (minimum, ISO 8601). Example: 2024-01-01T00:00:00Z.
​
endDate
string
Filter by date (maximum, ISO 8601).
​
search
string
Search in order name/number (max 200 characters).
​
sortBy
string
default:"createdAt"
Sort field. One of: createdAt, orderId, orderNumber, shipDate, deliveryDate, totalSales, totalPayout.
​
sortOrder
string
default:"desc"
Sort direction. One of: asc, desc.
​
first
integer
Number of items to return, forward pagination (1–100).
​
after
string
Cursor for forward pagination.
​
last
integer
Number of items to return, backward pagination (1–100).
​
before
string
Cursor for backward pagination.

​
Response

200
{
  "success": true,
  "data": {
    "orders": [
      {
        "_id": "507f1f77bcf86cd799439013",
        "orderId": 5123456789,
        "orderNumber": 1042,
        "orderName": "#1042",
        "orderSummary": {
          "totalPrice": 299.99,
          "subTotalPrice": 279.99,
          "totalTax": 20.00,
          "currency": "GBP"
        },
        "customer": {
          "email": "customer@example.com",
          "firstName": "Jane",
          "lastName": "Doe"
        },
        "status": "fulfilled",
        "createdAt": "2024-06-15T10:30:00.000Z"
      }
    ],
    "totalCount": 350,
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMyJ9",
      "endCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAyMCJ9"
    }
  }
}

​
Example

curl -X GET "https://api.puppetvendors.com/v2/orders?first=20&status=fulfilled" \
  -H "x-access-token: YOUR_JWT_TOKEN"