API referenceShipments

Create a shipment

Purchases a quoted rate and creates the shipment under your shipper account.

POST/shipments

https://sandbox.api.mothership.com/beta

curl --request POST \
  --url 'https://sandbox.api.mothership.com/beta/shipments' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "quoteId": "-LaLqLBycik7COnRuq5P",
  "rateId": "G6EMET"
}'

Reads your token from $MOTHERSHIP_API_TOKEN

Response

{

: {

: "MS5016101",

: "2025-01-28T23:09:53.149Z",

: "https://dashboard.mothership.com/track/MS5016101",

: "Unallocated",

: 87.67,

: "2025-01-29T16:00:00.000Z",

: "2025-01-30T01:00:00.000Z",

: [

{

: 2,

: "Pallet",

: 50,

: 48,

: 42,

: 46,

: "T-shirts"

}

: {

: "a3039151-6857-4659-bd8b-c0fce5e30a36",

: "Griffith Observatory",

: "2800 East Observatory Road",

: "Los Angeles",

: "CA",

: "90027",

: "America/Los_Angeles",

: [

"liftgate"

: "+15555555555",

: "0800",

: "1700",

: [

"logistics@mothership.com"

]

: {

: "1dfbde69-bf4e-48e0-9c4b-5699f8f35646",

: "LACMA",

: "5905 Wilshire Boulevard",

: "Los Angeles",

: "CA",

: "90036",

: "America/Los_Angeles",

: [

"liftgate",

"residential"

: "+15555555555",

: "1000",

: "2200",

: []

}

Hover a key to see what it means. Click it to jump to the field.

Purchasing a shipment will use the default payment source that the user's organization has on file. The payment source can be changed by logging in to the customer dashboard and updating the payment information in the organization's settings.

If the quote is missing details needed for purchase, the request fails with QUOTE_NOT_PURCHASABLE and metadata.invalidFieldsRequiredForPurchase lists them. A payment problem fails with 402 PAYMENT_FAILED. See Error handling.

Authorization

Authorization: Bearer <token>

Your sandbox API token. See Authentication.

Request body

application/json · required

quoteIdstringRequired
ID of the quote to purchase and turn into a shipment, from Create a quote.
rateIdstringRequired
ID of the rate to purchase. It must be one of the rates returned in the quote for quoteId.

Responses

- dataobjectRequired
  idstringRequired
  ID of the created shipment
  createdAtstring<date-time>Required
  When the shipment was created, as an ISO 8601 date-time.
  pricenumberRequired
  Price paid, in USD, for the shipment
  earliestPickupDatestring<date-time>Required
  Earliest pickup time for this shipment, as an ISO 8601 date-time.
  estimatedDeliveryDatestring<date-time>Required
  Estimated latest delivery time for this shipment, as an ISO 8601 date-time.
  freightarray of objectsRequired
  The freight, one array element per line item.
  min items 1
  pickupobjectRequired
  Pickup location of the shipment
  deliveryobjectRequired
  Delivery location of the shipment
  statusstring
  Current status of the shipment
  trackingUrlstring
  Tracking URL for the shipment.

What's next

GETTrack a shipment

Follow the shipment with data.id as the shipmentId.

POSTCreate a webhook configuration

Have each status change sent to your server as it happens.

GETList shipment documents

Download the bill of lading once it is ready.