---
title: "Create a shipment/offer"
method: POST
path: "/shipments"
tags: ["Shipper"]
---

# Create a shipment/offer

`POST /shipments`

Creates a shipment based on the factors provided in the request body. This API endpoint can only be accessed by Admins and Shippers!
`action` - add, update, cancel

## Request body

- OfferRequest
  - `action` string, required — Operation to perform on the shipment. One of `add`, `update`, or `cancel`.
  - `shipment` object, required — The shipment/offer to create or modify.
    - `reference_numbers` object[], required — Reference numbers for the shipment. Mark one as `primary` to use it as the main reference.
      - `name` string — Identifier for the reference number.
      - `primary` boolean — Whether this is the shipment's primary reference number.
      - `value` string — Value of the reference number.
    - `shipment_type` string, required — Type of shipment, e.g. `shorthaul` or `drayage`.
    - `shipper` string, required — ID of the shipper the offer is created for.
    - `stops` object[], required — Ordered list of pickup and delivery stops for the shipment.
      - `sequence` integer, required — Position of this stop within the shipment, starting at 1.
      - `location` object, required — Where this stop takes place.
        - `name` string, required — Name of the location.
        - `address` string, required — Street address of the location.
        - `suite_or_apt` string — Suite or apartment number, if applicable.
      - `loads` object[] — Loads picked up or delivered at this stop. Each entry describes a unit's type, quantity, dimensions, and weight.
        - `type` string
        - `quantity` integer
        - `width` integer
        - `height` integer
        - `length` integer
        - `weight` integer
      - `contacts` object[] — Contacts for this stop.
        - `name` string — Contact name.
        - `email` string — Contact email address.
        - `phone` string — Contact phone number.
      - `action` string, required — Action performed at this stop, either `pickup` or `delivery`.
      - `window_start` string, date-time, required — Start of the pickup/delivery window for this stop.
      - `window_end` string, date-time, required — End of the pickup/delivery window for this stop.
      - `reference_numbers` object[] — Reference numbers specific to this stop.
        - `name` string — Identifier for the reference number.
        - `value` string — Value of the reference number.
    - `loads` object[], required — Shipment-level loads, used when loads are not broken out per stop.
      - `type` string
      - `quantity` integer
      - `width` integer
      - `height` integer
      - `length` integer
      - `weight` integer
    - `accessorials` object[], required — Optional accessorial services requested for the shipment.
      - `type` string — Type of accessorial service.
    - `weight` integer, required — Total weight of the shipment, in pounds.
    - `notes` string, required — Free-text notes about the shipment.

## Response `200`

Status Code 200: Successful Response - the request was successful!

- OfferResponse
  - `action` string
  - `shipment` object
    - `shipment_type` string
    - `shipper` string
    - `reference_numbers` object[]
      - `name` string
      - `value` string
      - `primary` boolean
    - `stops` object[]
      - `sequence` integer
      - `location` object
        - `name` string
        - `address` string
        - `suite_or_apt` string
      - `loads` object[]
        - `type` string
        - `quantity` integer
        - `width` integer
        - `height` integer
        - `length` integer
        - `weight` integer
      - `contacts` object[]
        - `name` string
        - `email` string
        - `phone` string
      - `action` string
      - `window_start` string, date-time
      - `window_end` string, date-time
      - `reference_numbers` object[]
        - `name` string
        - `value` string
    - `loads` object[]
      - `type` string
      - `quantity` integer
      - `width` integer
      - `height` integer
      - `length` integer
      - `weight` integer
    - `accessorials` object[]
      - `type` string
    - `weight` integer
    - `notes` string

## Other responses

- `400` — Status Code 400: Bad Request Response - the request header and/or body is invalid
- `500` — Status Code 500: Internal Server Error Response - there's a problem with the Public API service

---

[API](https://skmtc.dev/cargomatic/apis/cargomatic-public-api.md) · [All operations](https://skmtc.dev/cargomatic/apis/cargomatic-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cargomatic/cargomatic-public-api/revisions/f9a170e1fd72/schema)