---
agentTools:
  projectIndex: https://wonderment.readme.io/llms.txt
---

# Search shipments

Search shipments for the authenticated shop by order name or tracking code. Requests require a Wonderment API access token with shipment read access. Some shops also require customer verification with the optional `t` query parameter.

Search shipments for the authenticated shop by order name or tracking code. Requests require a Wonderment API access token with shipment read access. The optional `t` query parameter is separate customer verification and is only required when customer search authentication is enabled for the shop.

## Creating the `t` token

The `t` parameter must be Base64-encoded JSON containing the search `query` and either the customer's `email` or `phone`. The `query` can be an order name or tracking code and overrides the `searchTerm` in the URL.

Use `JSON.stringify` so the value passed to `btoa` is valid JSON:

```javascript
const t = btoa(
  JSON.stringify({
    email: "customer@example.com",
    query: "1049"
  })
)
```

Then include the token as a query parameter:

```javascript
const url = `https://api.wonderment.com/2022-10/shipments/search/1049?t=${encodeURIComponent(t)}`
```

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Wonderment API",
    "description": "Wonderment Api",
    "version": "latest"
  },
  "paths": {
    "/2022-10/shipments/search/{searchTerm}": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "description": "Search shipments for the authenticated shop by order name or tracking code. Requests require a Wonderment API access token with shipment read access. Some shops also require customer verification with the optional `t` query parameter.",
        "parameters": [
          {
            "name": "searchTerm",
            "in": "path",
            "required": true,
            "description": "Order name or tracking code associated with the shipment.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "t",
            "in": "query",
            "required": false,
            "description": "Base64-encoded customer verification payload. When provided, it can override `searchTerm` with its `query` value and should include the customer `email` or `phone`. Required only when customer search authentication is enabled for the shop.",
            "schema": {
              "type": "string",
              "example": "eyJxdWVyeSI6IjEwMDEiLCJlbWFpbCI6ImN1c3RvbWVyQGV4YW1wbGUuY29tIn0="
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "nullable": true,
                  "description": "Returns null when no matching order or tracking code is found.",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Order name for the matched shipment search result."
                    },
                    "shipments": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "trackingUrl": {
                            "type": "string",
                            "nullable": true
                          },
                          "trackingCode": {
                            "type": "string"
                          },
                          "carrierName": {
                            "type": "string"
                          },
                          "eta": {
                            "type": "string",
                            "nullable": true,
                            "description": "Estimated delivery timestamp when available. Pending fallback responses may return the literal value pending."
                          },
                          "serviceLevel": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "token": {
                                "type": "string"
                              }
                            }
                          },
                          "order": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "Numeric Shopify order ID, returned without the gid://shopify/Order/ prefix."
                              },
                              "name": {
                                "type": "string",
                                "description": "Shopify order name, such as #1001."
                              }
                            }
                          },
                          "statusDetails": {
                            "type": "object",
                            "properties": {
                              "trackingCode": {
                                "type": "string"
                              },
                              "details": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "description": "Wonderment shipment status."
                              },
                              "substatus": {
                                "type": "string",
                                "description": "Carrier-provided substatus."
                              },
                              "date": {
                                "type": "string",
                                "description": "Event timestamp. When timezone data is available, this uses the event timezone value."
                              },
                              "city": {
                                "type": "string",
                                "nullable": true
                              },
                              "state": {
                                "type": "string",
                                "nullable": true
                              },
                              "zip": {
                                "type": "string",
                                "nullable": true
                              },
                              "country": {
                                "type": "string",
                                "nullable": true
                              },
                              "trackingUrl": {
                                "type": "string",
                                "nullable": true
                              },
                              "eta": {
                                "type": "string",
                                "nullable": true
                              },
                              "isTimezoneProvided": {
                                "type": "boolean",
                                "nullable": true,
                                "description": "Whether the event timestamp included an explicit timezone."
                              },
                              "displayTimezone": {
                                "type": "string",
                                "nullable": true,
                                "description": "Display timezone for the event location, when available."
                              },
                              "createdAt": {
                                "type": "string",
                                "nullable": true,
                                "description": "Timestamp when the event was stored."
                              },
                              "locationDisplay": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "description": "Most recent shipment event. Omitted when the shipment has no non-expired events."
                          },
                          "events": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "trackingCode": {
                                  "type": "string"
                                },
                                "details": {
                                  "type": "string"
                                },
                                "status": {
                                  "type": "string",
                                  "description": "Wonderment shipment status."
                                },
                                "substatus": {
                                  "type": "string",
                                  "description": "Carrier-provided substatus."
                                },
                                "date": {
                                  "type": "string",
                                  "description": "Event timestamp. When timezone data is available, this uses the event timezone value."
                                },
                                "city": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "state": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "zip": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "country": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "trackingUrl": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "eta": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "isTimezoneProvided": {
                                  "type": "boolean",
                                  "nullable": true,
                                  "description": "Whether the event timestamp included an explicit timezone."
                                },
                                "displayTimezone": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "Display timezone for the event location, when available."
                                },
                                "createdAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "Timestamp when the event was stored."
                                },
                                "locationDisplay": {
                                  "type": "string",
                                  "nullable": true
                                }
                              }
                            }
                          },
                          "lineItems": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "trackingCode": {
                                  "type": "string"
                                },
                                "lineItemId": {
                                  "type": "string",
                                  "description": "Numeric Shopify line item ID, returned without the gid://shopify/LineItem/ prefix."
                                },
                                "productImage": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "Image URL when available; may be an empty string."
                                },
                                "productName": {
                                  "type": "string",
                                  "description": "Product title stored from Shopify."
                                },
                                "variantName": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "Variant title stored from Shopify; may be an empty string."
                                },
                                "variantImage": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "Image URL when available; may be an empty string."
                                },
                                "sku": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "SKU stored from Shopify; may be an empty string."
                                },
                                "quantity": {
                                  "type": "integer",
                                  "nullable": true,
                                  "description": "Fulfilled quantity for this line item when available, otherwise the order line item quantity."
                                }
                              }
                            }
                          },
                          "date": {
                            "type": "string",
                            "nullable": true,
                            "description": "Present for pending/unfulfilled order fallback responses; ISO timestamp when included."
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "found": {
                    "summary": "Shipment found",
                    "value": {
                      "name": "#1001",
                      "shipments": [
                        {
                          "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111206213767912345",
                          "trackingCode": "9400111206213767912345",
                          "carrierName": "USPS",
                          "eta": "2026-04-24",
                          "serviceLevel": {
                            "name": "USPS Ground Advantage",
                            "token": "usps_ground_advantage"
                          },
                          "order": {
                            "id": "1234567890",
                            "name": "#1001"
                          },
                          "statusDetails": {
                            "trackingCode": "9400111206213767912345",
                            "details": "Delivered, In/At Mailbox",
                            "status": "DELIVERED",
                            "substatus": "delivered",
                            "date": "2026-04-24T14:32:00",
                            "city": "Austin",
                            "state": "TX",
                            "zip": "78701",
                            "country": "US",
                            "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111206213767912345",
                            "eta": "2026-04-24",
                            "createdAt": "2026-04-24T14:36:12+0000",
                            "locationDisplay": "Austin, TX, 78701, US",
                            "isTimezoneProvided": false,
                            "displayTimezone": "America/Chicago"
                          },
                          "events": [
                            {
                              "trackingCode": "9400111206213767912345",
                              "details": "Shipping label created",
                              "status": "PRE_TRANSIT",
                              "substatus": "information_received",
                              "date": "2026-04-21T09:15:00",
                              "city": "Austin",
                              "state": "TX",
                              "zip": "78701",
                              "country": "US",
                              "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111206213767912345",
                              "eta": "2026-04-24",
                              "createdAt": "2026-04-21T09:18:03+0000",
                              "locationDisplay": "Austin, TX, 78701, US",
                              "isTimezoneProvided": false,
                              "displayTimezone": "America/Chicago"
                            },
                            {
                              "trackingCode": "9400111206213767912345",
                              "details": "Delivered, In/At Mailbox",
                              "status": "DELIVERED",
                              "substatus": "delivered",
                              "date": "2026-04-24T14:32:00",
                              "city": "Austin",
                              "state": "TX",
                              "zip": "78701",
                              "country": "US",
                              "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111206213767912345",
                              "eta": "2026-04-24",
                              "createdAt": "2026-04-24T14:36:12+0000",
                              "locationDisplay": "Austin, TX, 78701, US",
                              "isTimezoneProvided": false,
                              "displayTimezone": "America/Chicago"
                            }
                          ],
                          "lineItems": [
                            {
                              "trackingCode": "9400111206213767912345",
                              "lineItemId": "9876543210",
                              "productImage": "https://cdn.shopify.com/s/files/example/product.jpg",
                              "productName": "Wonderment T-Shirt",
                              "variantName": "Medium / Black",
                              "variantImage": "https://cdn.shopify.com/s/files/example/variant.jpg",
                              "sku": "WM-TSHIRT-M-BLK",
                              "quantity": 1
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "notFound": {
                    "summary": "No matching shipment",
                    "value": null
                  },
                  "pending": {
                    "summary": "Order received, no tracking yet",
                    "value": {
                      "name": "#1002",
                      "shipments": [
                        {
                          "trackingCode": "",
                          "trackingUrl": null,
                          "carrierName": "",
                          "date": "2026-04-21T09:15:00.000Z",
                          "eta": "pending",
                          "serviceLevel": {
                            "name": "",
                            "token": ""
                          },
                          "statusDetails": {
                            "status": "PENDING",
                            "substatus": "order_received",
                            "date": "2026-04-21T09:15:00.000Z",
                            "details": "Order has been received"
                          },
                          "lineItems": [],
                          "events": [],
                          "order": {
                            "id": "1234567891",
                            "name": "#1002"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid search term.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "message": "Invalid request. Must include search term."
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed or customer verification failed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "authenticationFailed": {
                    "value": {
                      "message": "401: Authentication Failed"
                    }
                  },
                  "orderNotFound": {
                    "value": {
                      "message": "We couldn't find that order"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Shop does not have an active paid plan for API access.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "message": "Upgrade to a Wonderment paid plan for access."
                }
              }
            }
          },
          "403": {
            "description": "Token does not include shipment read access."
          }
        },
        "summary": "Search shipments"
      }
    }
  },
  "security": [
    {
      "apiKeyHeader": []
    }
  ],
  "servers": [
    {
      "url": "https://api.wonderment.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKeyHeader": {
        "type": "apiKey",
        "name": "X-Wonderment-Access-Token",
        "in": "header"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 99,
      "1": 98,
      "2": 193,
      "3": 114,
      "4": 16,
      "5": 19,
      "6": 67,
      "7": 0,
      "8": 176,
      "9": 227,
      "10": 126,
      "11": 76
    }
  }
}
```