---
title: "Create a new shipment"
method: POST
path: "/v1/shipper/shipment"
tags: ["Shipper API"]
---

# Create a new shipment

`POST /v1/shipper/shipment`

## Request

- Base URL: `https://api.oway.io`
- URL: `https://api.oway.io/v1/shipper/shipment`
- Auth: HTTP bearer and API key in header `x-oway-api-key`

Creates a new shipment order. Optionally reference a previously generated quote. The shipment must be confirmed after creation.

**Note:** The `companyId` is automatically extracted from your API key.
You do not need to provide this value in the request body.

For M2M (machine-to-machine) integrations, no user context is required.

## Headers

- `Idempotency-Key` string

## Request body

- CreateShipmentRequest: Request to create a new shipment
  - `quoteId` string: Optional ID of a previously generated quote.
  - `pickupAddress` Address, required: Address information for pickup or delivery locations
    - `name` string, required: Name of the location or business
    - `address1` string, required: Primary street address
    - `address2` string: Secondary address line (suite, unit, etc.)
    - `city` string, required: City name
    - `state` string, required: Two-letter subdivision code. A request must name a US state, territory or DC; a response may name the subdivision of another country, which country names.
    - `zipCode` string, required: 5-digit ZIP code. The placeholders 00000 and 99999 are rejected: neither is an assignable USPS code, and both are what a caller sends when a numeric ZIP field defaults to zero or saturates.
    - `country` string: Two-letter ISO 3166-1 alpha-2 country code, case-insensitive and normalized to upper case. Defaults to US when omitted. Oway currently serves the US and its territories, so US, PR, GU, VI, AS and MP are accepted and any other recognized code is rejected with 400 rather than quoted. A territory may also be addressed the way a carrier would, as country US with the territory in state.
    - `phoneNumber` string, required: Contact phone number in E.164 format
    - `contactPerson` string, required: Name of the contact person at this location
    - `phoneExtension` string: Phone extension, dialled after the main number
    - `email` string, email: Contact email for this location
    - `openTime` string: Opening time for the location in 24-hour format (HH:mm). Defaults to 10:00 if not provided.
    - `closeTime` string: Closing time for the location in 24-hour format (HH:mm). Defaults to 16:00 if not provided.
    - `notes` string: Additional notes or instructions for the driver
    - `liftgateRequired` boolean: Whether a liftgate is required at this location
    - `limitedAccess` boolean: Whether this is a limited access location (residential, construction site, etc.)
    - `appointmentRequired` boolean: Whether an appointment is required for pickup/delivery
    - `callAheadRequired` boolean: Whether a call-ahead notification is required before pickup/delivery. When true, the carrier will call the contact person before arriving at the location.
    - `lumperRequired` boolean: Whether third-party lumper labor loads/unloads at this location (common at large distribution centers where drivers may not handle freight). Informational for quoting: the lumper fee is not priced into the quote and is billed after delivery as a separate charge with proof of payment.
    - `insideRequired` boolean: Whether the driver must bring freight inside the facility rather than to the dock or curb. Adds a flat inside-service fee to the quote.
  - `deliveryAddress` Address, required: Address information for pickup or delivery locations
    - `name` string, required: Name of the location or business
    - `address1` string, required: Primary street address
    - `address2` string: Secondary address line (suite, unit, etc.)
    - `city` string, required: City name
    - `state` string, required: Two-letter subdivision code. A request must name a US state, territory or DC; a response may name the subdivision of another country, which country names.
    - `zipCode` string, required: 5-digit ZIP code. The placeholders 00000 and 99999 are rejected: neither is an assignable USPS code, and both are what a caller sends when a numeric ZIP field defaults to zero or saturates.
    - `country` string: Two-letter ISO 3166-1 alpha-2 country code, case-insensitive and normalized to upper case. Defaults to US when omitted. Oway currently serves the US and its territories, so US, PR, GU, VI, AS and MP are accepted and any other recognized code is rejected with 400 rather than quoted. A territory may also be addressed the way a carrier would, as country US with the territory in state.
    - `phoneNumber` string, required: Contact phone number in E.164 format
    - `contactPerson` string, required: Name of the contact person at this location
    - `phoneExtension` string: Phone extension, dialled after the main number
    - `email` string, email: Contact email for this location
    - `openTime` string: Opening time for the location in 24-hour format (HH:mm). Defaults to 10:00 if not provided.
    - `closeTime` string: Closing time for the location in 24-hour format (HH:mm). Defaults to 16:00 if not provided.
    - `notes` string: Additional notes or instructions for the driver
    - `liftgateRequired` boolean: Whether a liftgate is required at this location
    - `limitedAccess` boolean: Whether this is a limited access location (residential, construction site, etc.)
    - `appointmentRequired` boolean: Whether an appointment is required for pickup/delivery
    - `callAheadRequired` boolean: Whether a call-ahead notification is required before pickup/delivery. When true, the carrier will call the contact person before arriving at the location.
    - `lumperRequired` boolean: Whether third-party lumper labor loads/unloads at this location (common at large distribution centers where drivers may not handle freight). Informational for quoting: the lumper fee is not priced into the quote and is billed after delivery as a separate charge with proof of payment.
    - `insideRequired` boolean: Whether the driver must bring freight inside the facility rather than to the dock or curb. Adds a flat inside-service fee to the quote.
  - `orderComponents` OrderComponent[], required: List of cargo components in the shipment
    - `palletCount` integer, required: Number of pallets in this component
    - `poundsWeight` integer, required: Weight per pallet in pounds
    - `palletDimensions` integer[]: Pallet dimensions as [height, length, width] in inches. Deprecated: prefer the 'dimensions' object. Optional: if both 'palletDimensions' and 'dimensions' are omitted, the API defaults to 40 x 48 x 60 in. (length x width x height).
    - `dimensions` Dimensions: Pallet dimensions in inches. All fields optional: if any are omitted the entire dimensions object is treated as missing and the API default of 40 x 48 x 60 in. (length x width x height) is applied.
      - `length` integer: Length in inches
      - `width` integer: Width in inches
      - `height` integer: Height in inches
    - `description` string: Per-component freight description (e.g. NMFC item name)
    - `nmfcCode` string: NMFC commodity code for this component
    - `freightClass` string: LTL freight class declared by the shipper. When supplied it is authoritative; Oway derives a class from density only when this is absent.
    - `packagingType` string: Packaging type for this component (e.g. Pallets, Boxes, Crates)
    - `pieceCount` integer: Number of pieces (loose items) in this component, distinct from pallet count
  - `description` string, required: Description of the shipment contents
  - `poNumber` string: Purchase order number for reference
  - `refNumber` string: Your reference number for this shipment (typically your Bill of Lading number). Prints on partner-branded BOLs alongside the Oway order number.
  - `instructions` string: Free-text instructions to render on the shipment's documents. Matches the instructions field on appointment requirements.
  - `referenceNumbers` string[]: Reference numbers (PO, customer pickup #, etc.) to render on the shipment's documents, beyond poNumber and refNumber. Up to 100 entries, each at most 128 characters; supplied order and repeated values are preserved.
  - `requiredPickupDate` string, date-time: Required pickup date (ISO 8601). Read as a calendar day, its UTC date; send the date at midnight or noon UTC.
  - `requiredDeliveryBy` string, date-time: Required delivery date (ISO 8601). Read as a calendar day, its UTC date; the deadline is the delivery stop's closing time on that day, in the stop's time zone.
  - `appointments` AppointmentsBlock: Optional inline-on-create block on POST /v1/shipper/shipment. Each entry is the AppointmentRequirementRequest for the corresponding stop, applied only if that address has appointmentRequired=true.
    - `pickup` AppointmentRequirementRequest: Structured appointment metadata for a single stop on an order. Sent on PUT /v1/shipper/shipment/{orderNumber}/appointment/{stop} or via the appointments block on POST /v1/shipper/shipment.
      - `channel` 'PHONE' | 'EMAIL' | 'PORTAL', required: How the appointment is scheduled
      - `portalUrl` string: Portal URL where the carrier will book the appointment. Required when channel == PORTAL, must be omitted otherwise.
      - `contacts` AppointmentContact[]: Contacts the carrier can use to schedule the appointment
        - `name` string, required: Contact name
        - `email` string, email: Email address
        - `phone` string: Phone in E.164 format
        - `role` string: Role of the contact at the facility
      - `instructions` string: Free-text instructions shown to the carrier. Max 2000 chars.
      - `referenceNumbers` string[]: Reference numbers (PO, customer pickup #, etc.) the carrier will be asked for. Max 10 entries, each max 64 chars.
      - `leadTimeHours` integer: Minimum advance notice (in hours) the receiver requires. 0–168.
    - `delivery` AppointmentRequirementRequest: Structured appointment metadata for a single stop on an order. Sent on PUT /v1/shipper/shipment/{orderNumber}/appointment/{stop} or via the appointments block on POST /v1/shipper/shipment.
      - `channel` 'PHONE' | 'EMAIL' | 'PORTAL', required: How the appointment is scheduled
      - `portalUrl` string: Portal URL where the carrier will book the appointment. Required when channel == PORTAL, must be omitted otherwise.
      - `contacts` AppointmentContact[]: Contacts the carrier can use to schedule the appointment
        - `name` string, required: Contact name
        - `email` string, email: Email address
        - `phone` string: Phone in E.164 format
        - `role` string: Role of the contact at the facility
      - `instructions` string: Free-text instructions shown to the carrier. Max 2000 chars.
      - `referenceNumbers` string[]: Reference numbers (PO, customer pickup #, etc.) the carrier will be asked for. Max 10 entries, each max 64 chars.
      - `leadTimeHours` integer: Minimum advance notice (in hours) the receiver requires. 0–168.
  - `shipperDispatch` ShipperDispatch: The operational dispatch contact for this shipment. Distinct from the shipper company itself, this is the desk or person responsible for answering questions about the load. At least one of email or phone must be present.
    - `name` string, required: Dispatch contact name
    - `email` string, email: Dispatch email
    - `phone` string: Dispatch phone in E.164 format
    - `scac` string: Standard Carrier Alpha Code (SCAC), if applicable

## Response `200`

Shipment created successfully

- Shipment: Shipment/Order details
  - `id` string: Unique identifier for the order
  - `companyId` string: Company ID that owns this order
  - `userId` string: User ID who created this order
  - `orderNumber` string: Human-readable PRO number for the shipment (5-character alphanumeric)
  - `orderStatus` 'INITIALIZED' | 'CONFIRMED' | 'ACCEPTED' | 'ASSIGNED' | 'PICKED_UP' | 'IN_TRANSIT' | 'DELIVERED' | 'CANCELLED' | 'REJECTED': Current status of the order
  - `totalPriceInCents` integer: Total price of the order in cents (USD)
  - `createdAt` string, date-time: Time when the order was created (ISO 8601 format)
  - `updatedAt` string, date-time: Time when the order was last updated (ISO 8601 format)

## Other responses

- `400`: Invalid request: validation error, quote mismatch, or expired quote
- `401`: Unauthorized: missing or invalid Bearer token (authentication failed)
- `403`: Forbidden: missing/invalid API key, user not in company, or quote not owned by company
- `422`: Unprocessable Entity. `reason` carries the coverage denial code, unmodified. Possible reasons: - **Location Not Serviceable** (`reason: no_aggregate_coverage`, `no_eligible_carriers`, or the legacy `no_coverage`): no carrier is known to serve this lane yet. - **Below Pallet Minimum** (`reason: min_pallets`): the shipment is under the minimum pallet count for this lane. - **Above Pallet Maximum** (`reason: max_pallets`): the shipment is over the maximum pallet count for this lane. - **Lane Not Available For Your Account** (`reason: coverage_denied`, `origin_policy_denied`, or `destination_policy_denied`): a coverage rule on your account excludes this lane or one of its endpoints. Contact your Oway representative for details. - **Above Your Coverage Level** (`reason: max_tier_capped`): carriers serve this lane, but it does not yet meet the level of proven coverage your account is set to accept. Contact your Oway representative to review that setting. - **Outside Service Area** (`reason: outside_service_area`): a pickup or delivery point is outside an area Oway serves. - **Excluded Toll Region** (`reason: excluded_toll_region`): the lane crosses a region excluded for your account. - **Request Not Permitted** (`reason: account_restriction`): the requested truck type or accessorial is not enabled for your account. Contact your Oway representative to update your available options. - **Daily Trip Limit Reached** (`reason: daily_trip_limit`): your account has reached its maximum shipments for the requested pickup date. You can still place orders for other dates. - **Pallet Shape Not Shippable** (`reason: pallet_invalid`): one or more pallets exceed Oway's dimension or weight limits; per-field details are in `violations`. - **Pricing Unavailable** (`reason: pricing_unavailable`): the lane could not be priced. Contact your Oway representative for assistance. - **No Road Route** (`reason: no_road_route`): no road connects the pickup and delivery locations (for example, the mainland and Hawaii or Puerto Rico), so the lane can't be served by truck.
- `500`: Internal server error

---

[API](https://skmtc.dev/shipoway/apis/oway-shipper-api.md) - [All operations](https://skmtc.dev/shipoway/apis/oway-shipper-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shipoway/apis/oway-shipper-api/revisions/35141ac5fb57?raw)