# List shipments `GET https://api.mothership.com/beta/shipments` Sandbox: `https://sandbox.api.mothership.com/beta/shipments` Lists all shipments booked by your organization. This endpoint returns an array of shipments stored in the response body's `results` property. Pagination behavior can be controlled by providing `page` and `perPage` query parameters. If none are provided, `page` will default to `1`, and `perPage` will default to `25`. `perPage` cannot exceed `100`. The `hasMore` property in the response payload indicates if there are additional shipments that can be fetched by incrementing the `page` query parameter. ## Authorization Send your API token as a Bearer token: `Authorization: Bearer `. ## Query parameters - `perPage` (number, optional): Maximum number of shipments to return per page. Defaults to 25. - `page` (number, optional): Page to return, starting at 1. Defaults to 1. ## Responses ### 200 Shipment details, inside `data`. - `data` (object, optional) - `perPage` (number, required): Maximum number of shipments per page. - `page` (number, required): Current page of shipments. - `hasMore` (boolean, required): True if a later page has more shipments. - `results` (array of objects, optional) - `id` (string, required): ID of the created shipment. - `createdAt` (string, required): When the shipment was created, as an ISO 8601 date-time. - `price` (number, required): Price paid, in USD, for the shipment. - `earliestPickupDate` (string, required): Earliest pickup time for this shipment, as an ISO 8601 date-time. - `estimatedDeliveryDate` (string, required): Estimated latest delivery time for this shipment, as an ISO 8601 date-time. - `freight` (array of objects, required, min items 1): The freight, one array element per line item. - `quantity` (number, required): Quantity of this cargo line item. - `type` (string, required): Type of this cargo. Can be: Bag, Bale, Box, Bucket, Bundle, Can, Carton, Case, Coil, Crate, Cylinder, Drum, Pail, Pallet, Pieces, Reel, Roll, Skid, Tote, or Tube. LooseItem has been deprecated in favor of Pieces. One of: `Bag`, `Bale`, `Box`, `Bucket`, `Bundle`, `Can`, `Carton`, `Case`, `Coil`, `Crate`, `Cylinder`, `Drum`, `Pail`, `Pallet`, `Pieces`, `Reel`, `Roll`, `Skid`, `Tote`, `Tube`. - `weight` (integer, required, min 1): Weight of each item in this line item, in pounds. For example, a 1,600 lb shipment of 4 pallets at 400 lb each has a `weight` of 400. - `length` (integer, required, min 1): Length of each item in this line item, in inches. - `width` (integer, required, min 1): Width of each item in this line item, in inches. - `height` (integer, required, min 1): Height of each item in this line item, in inches. - `description` (string, optional): Cargo description of this line item. - `nmfcCode` (string, optional, pattern ^\d{3,10}(?:-\d{1,3})?$): NMFC code for this line item, as a 3-10 digit article number with an optional 1-3 digit sub-item suffix. For example: 156600 or 156600-03. - `freightClass` (string, optional): Freight class for this line item. When provided, this is the class used to rate the shipment -- it overrides our density-based classification, so you are responsible for its accuracy and the carrier may reclassify and adjust charges if it is incorrect. Omit this field to have the freight class calculated from the dimensions and weight you supply. One of: `50`, `55`, `60`, `65`, `70`, `77.5`, `85`, `92.5`, `100`, `110`, `125`, `150`, `175`, `200`, `250`, `300`, `400`, `500`. - `pieceCount` (integer, optional, min 1): Number of pieces in each handling unit, printed on the bill of lading. For example, for 4 pallets of 5 cartons each, set `pieceCount` to 5 and `quantity` to 4. - `pieceType` (string, optional): Packaging of the pieces inside each handling unit. Can be: Bag, Barrel, Bolt, Box, Canister, Carton, Case, Container, Crate, Cylinder, Pieces, Roll, or Tube. This is usually different from the cargo type: 4 pallets each holding 5 cartons is type Pallet, quantity 4, pieceType Carton, pieceCount 5. One of: `Bag`, `Barrel`, `Bolt`, `Box`, `Canister`, `Carton`, `Case`, `Container`, `Crate`, `Cylinder`, `Pieces`, `Roll`, `Tube`. - `pickup` (object, required): Pickup location of the shipment. - `city` (string, required): City. - `state` (string, required): Two-letter state abbreviation. - `zip` (string, required): ZIP code. - `placeId` (string, required, deprecated): Deprecated: use the `address` parameter instead. A place ID from the Fetch Places endpoint. - `accessorials` (array of strings, required, default [], unique items): Accessorials required at this location. One of: `alcohol`, `appointment`, `cfs`, `crossDock`, `hazmat`, `homeDelivery`, `inside`, `liftgate`, `limitedAccess`, `localInsideDelivery`, `notifyBeforeArrival`, `residential`, `scheduledDelivery`, `sortSeg`, `tobacco`, `tradeshow`, `twicRequired`. - `emails` (array of strings, required, default [], unique items): Email addresses that receive notification emails. - `openTime` (string, required, 4 characters, pattern ^[0-9]{4}$): When this location opens, as 4-digit 24-hour time (HHmm) in the location's timezone. Whole hours, with no minutes, are recommended. For example: 0900 for 9:00am local time. - `closeTime` (string, required, 4 characters, pattern ^[0-9]{4}$): When this location closes, as 4-digit 24-hour time (HHmm) in the location's timezone. Whole hours, with no minutes, are recommended. For example: 2200 for 10:00pm local time. - `name` (string, optional): Business or company name. - `street` (string, optional): Street address. - `subStreet` (string, optional, deprecated): Second address line, such as a suite number or letter. Deprecated: send it in the `address` field instead. - `timezone` (string, optional): IANA timezone of the location, such as America/Los_Angeles. Use it to convert the location's open and close times, and the shipment's UTC timestamps, to local time. - `phoneNumber` (string, optional): Contact phone number at this location, in E.164 format. For example: +17148130000. - `referenceNumber` (string, optional): Reference number for this location. - `notes` (string, optional): Notes for this location. - `delivery` (object, required): Delivery location of the shipment. - `city` (string, required): City. - `state` (string, required): Two-letter state abbreviation. - `zip` (string, required): ZIP code. - `placeId` (string, required, deprecated): Deprecated: use the `address` parameter instead. A place ID from the Fetch Places endpoint. - `accessorials` (array of strings, required, default [], unique items): Accessorials required at this location. One of: `alcohol`, `appointment`, `cfs`, `crossDock`, `hazmat`, `homeDelivery`, `inside`, `liftgate`, `limitedAccess`, `localInsideDelivery`, `notifyBeforeArrival`, `residential`, `scheduledDelivery`, `sortSeg`, `tobacco`, `tradeshow`, `twicRequired`. - `emails` (array of strings, required, default [], unique items): Email addresses that receive notification emails. - `openTime` (string, required, 4 characters, pattern ^[0-9]{4}$): When this location opens, as 4-digit 24-hour time (HHmm) in the location's timezone. Whole hours, with no minutes, are recommended. For example: 0900 for 9:00am local time. - `closeTime` (string, required, 4 characters, pattern ^[0-9]{4}$): When this location closes, as 4-digit 24-hour time (HHmm) in the location's timezone. Whole hours, with no minutes, are recommended. For example: 2200 for 10:00pm local time. - `name` (string, optional): Business or company name. - `street` (string, optional): Street address. - `subStreet` (string, optional, deprecated): Second address line, such as a suite number or letter. Deprecated: send it in the `address` field instead. - `timezone` (string, optional): IANA timezone of the location, such as America/Los_Angeles. Use it to convert the location's open and close times, and the shipment's UTC timestamps, to local time. - `phoneNumber` (string, optional): Contact phone number at this location, in E.164 format. For example: +17148130000. - `referenceNumber` (string, optional): Reference number for this location. - `notes` (string, optional): Notes for this location. - `status` (string, optional): Current status of the shipment. - `trackingUrl` (string, optional): Tracking URL for the shipment. ## Example request ```bash curl --request GET \ --url 'https://sandbox.api.mothership.com/beta/shipments' \ --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \ --header 'Accept: application/json' ``` ## Example response (200) ```json { "data": { "results": [ { "id": "MS5016101", "createdAt": "2019-03-19T17:03:24.542Z", "trackingUrl": "https://dashboard.mothership.com/track/MS5016101", "price": 79, "earliestPickupDate": "2019-03-19T17:15:55.000Z", "estimatedDeliveryDate": "2019-03-20T05:00:55.000Z", "status": "Unallocated", "freight": [ { "quantity": 2, "type": "Pallet", "weight": 50, "length": 48, "width": 42, "height": 46, "description": "T-shirts" } ], "pickup": { "placeId": "ChIJywjU6WG_woAR3NrWwrEH_3M", "name": "Griffith Observatory", "street": "2800 East Observatory Road", "city": "Los Angeles", "state": "CA", "zip": "90027", "accessorials": ["liftgate"], "phoneNumber": "+15555555555", "openTime": "1000", "closeTime": "2200", "emails": ["logistics@mothership.com"] }, "delivery": { "placeId": "ChIJsXqcyjy5woARNz6sOh0ZmwA", "name": "LACMA", "street": "5905 Wilshire Boulevard", "city": "Los Angeles", "state": "CA", "zip": "90036", "accessorials": ["liftgate", "residential"], "phoneNumber": "+15555555555", "openTime": "1000", "closeTime": "2200", "emails": [] } } ], "hasMore": false, "perPage": 20, "page": 2 } } ```