List Orders By Tag

Lists all orders that match the specified order status (orderStatus) and tag ID (tagId).

URL format with filters:

/listbytag?orderStatus={orderStatus}
&tagId={tagId}
&page={page}
&pageSize={pageSize}
Name Data Type Description
orderStatus string The order's status.

Possible values: "awaiting_payment", "awaiting_shipment", "shipped", "on_hold", "cancelled"

Required
tagId number ID of the tag.

Call Accounts - ListTags to obtain a list of tags for this account.

Required
page string Page number.

Optional
pageSize string Requested page size.

Max value is 500.

Optional

Example Request

GET /orders/listbytag?orderStatus=orderStatus&tagId=tagId&page=page&pageSize=pageSize HTTP/1.1
Host: ssapi.shipstation.com
Authorization: __YOUR_AUTH_HERE__

Example Request

{
  "orders": [
    {
      "orderId": 123456789,
      "orderNumber": "TEST-ORDER-API-DOCS",
      "orderKey": "0f6bec18-3e89-4881-83aa-f392d84f4c74",
      "orderDate": "2015-06-29T08:46:27.0000000",
      "createDate": "2015-08-17T09:43:03.0500000",
      "modifyDate": "2015-08-17T09:43:12.5500000",
      "paymentDate": "2015-06-29T08:46:27.0000000",
      "shipByDate": "2015-07-05T00:00:00.0000000",
      "orderStatus": "awaiting_shipment",
      "customerId": 37701499,
      "customerUsername": "[email protected]",
      "customerEmail": "[email protected]",
      "billTo": {
        "name": "The President",
        "company": null,
        "street1": null,
        "street2": null,
        "street3": null,
        "city": null,
        "state": null,
        "postalCode": null,
        "country": null,
        "phone": null,
        "residential": null,
        "addressVerified": null
      },
      "shipTo": {
        "name": "The President",
        "company": "US Govt",
        "street1": "1600 Pennsylvania Ave",
        "street2": "Oval Office",
        "street3": null,
        "city": "Washington",
        "state": "DC",
        "postalCode": "20500",
        "country": "US",
        "phone": "555-555-5555",
        "residential": false,
        "addressVerified": "Address validation warning"
      },
      "items": [
        {
          "orderItemId": 136289188,
          "lineItemKey": "vd08-MSLbtx",
          "sku": "ABC123",
          "name": "Test item #1",
          "imageUrl": null,
          "weight": {
            "value": 24,
            "units": "ounces"
          },
          "quantity": 2,
          "unitPrice": 99.99,
          "taxAmount": 2.5,
          "shippingAmount": 5,
          "warehouseLocation": "Aisle 1, Bin 7",
          "options": [
            {
              "name": "Size",
              "value": "Large"
            }
          ],
          "productId": 7239919,
          "fulfillmentSku": null,
          "adjustment": false,
          "upc": "32-65-98",
          "createDate": "2015-08-17T09:43:03.05",
          "modifyDate": "2015-08-17T09:43:03.05"
        },
        {
          "orderItemId": 136289189,
          "lineItemKey": null,
          "sku": "DISCOUNT CODE",
          "name": "10% OFF",
          "imageUrl": null,
          "weight": {
            "value": 0,
            "units": "ounces"
          },
          "quantity": 1,
          "unitPrice": -20.55,
          "taxAmount": null,
          "shippingAmount": null,
          "warehouseLocation": null,
          "options": [],
          "productId": null,
          "fulfillmentSku": "SKU-Discount",
          "adjustment": true,
          "upc": null,
          "createDate": "2015-08-17T09:43:03.05",
          "modifyDate": "2015-08-17T09:43:03.05"
        }
      ],
      "orderTotal": 194.43,
      "amountPaid": 218.73,
      "taxAmount": 5,
      "shippingAmount": 10,
      "customerNotes": "Please ship as soon as possible!",
      "internalNotes": "Customer called and would like to upgrade shipping",
      "gift": true,
      "giftMessage": "Thank you!",
      "paymentMethod": "Credit Card",
      "requestedShippingService": "Priority Mail",
      "carrierCode": "fedex",
      "serviceCode": "fedex_2day",
      "packageCode": "package",
      "confirmation": "delivery",
      "shipDate": "2015-07-02",
      "holdUntilDate": null,
      "weight": {
        "value": 48,
        "units": "ounces"
      },
      "dimensions": {
        "units": "inches",
        "length": 7,
        "width": 5,
        "height": 6
      },
      "insuranceOptions": {
        "provider": "carrier",
        "insureShipment": true,
        "insuredValue": 200
      },
      "internationalOptions": {
        "contents": null,
        "customsItems": null,
        "nonDelivery": null
      },
      "advancedOptions": {
        "warehouseId": 98765,
        "nonMachinable": false,
        "saturdayDelivery": false,
        "containsAlcohol": false,
        "mergedOrSplit": false,
        "mergedIds": [],
        "parentId": null,
        "storeId": 12345,
        "customField1": "Custom data that you can add to an order. See Custom Fields #2 & #3 for more info!",
        "customField2": "Per UI settings, this information can appear on some carriers' shipping labels. See the link below",
        "customField3": "https://help.shipstation.com/hc/en-us/articles/206639957",
        "source": "Webstore",
        "billToParty": null,
        "billToAccount": null,
        "billToPostalCode": null,
        "billToCountryCode": null
      },
      "tagIds": [
        831
      ],
      "userId": "b854f701-e0c2-4156-90fe-19c77cdef27c",
      "externallyFulfilled": false,
      "externallyFulfilledBy": null,
      "externallyFulfilledById": 12345,
      "externallyFulfilledByName": "Example Fulfillment Provider Name"
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1
}