# Mothership API

> Quote, purchase and track Mothership freight shipments over a REST API. Sandbox: https://sandbox.api.mothership.com/beta. Production: https://api.mothership.com/beta.

## Guides: Booking a shipment

- [Introduction](https://developers.mothership.com/docs/booking-intro.md): Book a shipment end to end, from describing the freight to buying a rate.
- [Setting up authentication](https://developers.mothership.com/docs/booking-authentication.md): Create a sandbox token and send it with every request in this guide.
- [Getting rates](https://developers.mothership.com/docs/booking-rates.md): Create a quote for two pallets from Griffith Observatory to LACMA.
- [Booking the shipment](https://developers.mothership.com/docs/booking-order.md): Pick a rate from the quote and purchase it with Create a shipment.

## Guides: Tracking a shipment

- [Introduction](https://developers.mothership.com/docs/tracking-intro.md): Fetch tracking information for a shipment and keep up with its status.
- [Setting up authentication](https://developers.mothership.com/docs/tracking-authentication.md): Create a sandbox token and send it with every tracking request.
- [Getting tracking information](https://developers.mothership.com/docs/tracking-request.md): Read a shipment's status and tracking events, and know when to check again.

## Guides: Configuring webhooks

- [Setting up authentication](https://developers.mothership.com/docs/webhooks-authentication.md): Create a token for the webhook configuration requests in this guide.
- [Creating a webhook configuration](https://developers.mothership.com/docs/webhook-create.md): Subscribe an endpoint on your server to shipment and document events.
- [Receiving webhook requests](https://developers.mothership.com/docs/receiving-webhooks.md): The webhook request body, how fast events arrive, and how retries work.
- [Validating webhook payloads](https://developers.mothership.com/docs/webhooks-validation.md): Check the X-Mothership-Signature header with your webhook configuration's secret key.

## API reference: Getting started

- [Overview](https://developers.mothership.com/reference/overview.md): Quote, purchase and track Mothership shipments from your own software over a REST API.
- [Authentication](https://developers.mothership.com/reference/authentication.md): Send your API token as a Bearer token in the Authorization header.
- [Error handling](https://developers.mothership.com/reference/error-handling.md): HTTP status codes, the error response format and every error type the API returns.
- [Rate limiting](https://developers.mothership.com/reference/rate-limiting.md): Request limits per organization, the rate limit headers, and what to do when you hit a limit.
- [Webhooks](https://developers.mothership.com/reference/webhooks.md): The events Mothership can POST to your server, and what each payload contains.

## API reference: API

- Quotes
  - [Create a quote](https://developers.mothership.com/reference/createquote.md): Creates a quote from the shipment details you send. The response lists the available rates with their prices, and a quote ID to use with Create a shipment.
- Shipments
  - [List shipments](https://developers.mothership.com/reference/listshipments.md): Lists all shipments booked by your organization.
  - [Create a shipment](https://developers.mothership.com/reference/createshipment.md): Purchases a quoted rate and creates the shipment under your shipper account.
  - [Retrieve a shipment](https://developers.mothership.com/reference/getshipmentdetails.md): Returns up-to-date details for the shipment with the given shipment ID.
  - [Cancel a shipment](https://developers.mothership.com/reference/cancelshipment.md): Attempts to cancel the shipment immediately. By default, the request succeeds only when the cancellation path available right now is free. To accept a paid cancellation, set `acceptFees`, and optionally cap the fee with `limitAmountCents`.
- Tracking
  - [Track a shipment](https://developers.mothership.com/reference/fetchshipmenttracking.md): Lists the tracking events for a shipment.
- Documents
  - [List shipment documents](https://developers.mothership.com/reference/listshipmentdocuments.md): Generates URLs for a shipment's documents, such as the bill of lading and proof of delivery, when they are available.
- Files
  - [Retrieve a file](https://developers.mothership.com/reference/fetchfilebyid.md): Returns a download URL for the file with the given file ID.
- Invoices
  - [List modified invoices](https://developers.mothership.com/reference/listmodifiedinvoices.md): Takes an ISO 8601 timestamp and lists references to the invoices created or modified on or after it.
  - [List a shipment's invoices](https://developers.mothership.com/reference/listinvoicesbyshipmentid.md): Lists all invoices associated with a shipment.
  - [Retrieve an invoice](https://developers.mothership.com/reference/fetchinvoicebyid.md): Retrieves an invoice.
- Webhooks
  - [List webhook configurations](https://developers.mothership.com/reference/fetchwebhookconfigsforaccount.md): Lists all webhook configurations set up for your shipper account.
  - [Create a webhook configuration](https://developers.mothership.com/reference/createwebhookconfig.md): Creates a webhook configuration for your shipper account.
  - [Retrieve a webhook configuration](https://developers.mothership.com/reference/fetchwebhookconfig.md): Retrieves the webhook configuration with the given `webhookConfigId`.
  - [Update a webhook configuration](https://developers.mothership.com/reference/updatewebhookconfig.md): Updates the webhook configuration with the given `webhookConfigId`.
  - [Remove a webhook configuration](https://developers.mothership.com/reference/removewebhookconfig.md): Removes the webhook configuration with the given `webhookConfigId`.
- Account
  - [Retrieve your account](https://developers.mothership.com/reference/getaccount.md): Retrieves the details of your company account.

## API reference: Reference

- [Freight type](https://developers.mothership.com/reference/freight-type.md): The values freight items accept for type, pieceType and freightClass.
- [Shipment statuses](https://developers.mothership.com/reference/shipment-status.md): What each shipment status means and the order shipments usually move through them.
- [Accessorials](https://developers.mothership.com/reference/accessorials.md): The special services a quote can request at the pickup and delivery locations.
- [Rate services](https://developers.mothership.com/reference/rate-services.md): The service levels a rate's services array can contain.
- [Providers](https://developers.mothership.com/reference/providers.md): The carriers that provide rates, with their provider and SCAC values.
- [Invoice line items](https://developers.mothership.com/reference/invoice-line-items.md): What each invoice line item type means.

## Resources

- [OpenAPI document](https://developers.mothership.com/openapi.json): the public contract every page here is built from, version 0.9
- [All pages in one file](https://developers.mothership.com/llms-full.txt)
- Support: developers@mothership.com