SHshipoway
Shipper API

Create a new shipment

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.

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

Headers

Idempotency-Keystring

Optional idempotency key. Retrying the same request with the same key within 24h returns the original response without creating a second shipment. Reusing the key with a different body returns 409 idempotency_key_conflict.

Request body

quoteIdstring

Optional ID of a previously generated quote.

descriptionstring required

Description of the shipment contents

poNumberstring

Purchase order number for reference

refNumberstring

Your reference number for this shipment (typically your Bill of Lading number). Prints on partner-branded BOLs alongside the Oway order number.

instructionsstring

Free-text instructions to render on the shipment's documents. Matches the instructions field on appointment requirements.

referenceNumbersstring[]

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.

requiredPickupDatestring date-time

Required pickup date (ISO 8601). Read as a calendar day, its UTC date; send the date at midnight or noon UTC.

requiredDeliveryBystring 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.

Example request

{
  "quoteId": "507f1f77bcf86cd799439013",
  "pickupAddress": {
    "name": "Fairgrounds Distribution Center",
    "address1": "1531 Junipero Avenue",
    "address2": "Dock 5",
    "city": "Long Beach",
    "state": "CA",
    "zipCode": "90804",
    "country": "US",
    "phoneNumber": "+18087857650",
    "contactPerson": "Mike Johnson",
    "phoneExtension": "204",
    "email": "dock@example.com",
    "openTime": "10:00",
    "closeTime": "16:00",
    "notes": "Dock 3, enter from back of building",
    "appointmentRequired": true,
    "callAheadRequired": true
  },
  "deliveryAddress": {
    "name": "Fairgrounds Distribution Center",
    "address1": "1531 Junipero Avenue",
    "address2": "Dock 5",
    "city": "Long Beach",
    "state": "CA",
    "zipCode": "90804",
    "country": "US",
    "phoneNumber": "+18087857650",
    "contactPerson": "Mike Johnson",
    "phoneExtension": "204",
    "email": "dock@example.com",
    "openTime": "10:00",
    "closeTime": "16:00",
    "notes": "Dock 3, enter from back of building",
    "appointmentRequired": true,
    "callAheadRequired": true
  },
  "orderComponents": [
    {
      "palletCount": 2,
      "poundsWeight": 500,
      "palletDimensions": [
        72,
        48,
        48
      ],
      "dimensions": {
        "length": 48,
        "width": 48,
        "height": 72
      },
      "description": "Stone NOI",
      "nmfcCode": "90500-04",
      "freightClass": "100",
      "packagingType": "Pallets"
    }
  ],
  "description": "Electronics - fragile",
  "poNumber": "PO-2024-12345",
  "refNumber": "BOL-2026-04129",
  "instructions": "Call receiving before arrival; dock 4 only.",
  "referenceNumbers": [
    "SO-45821",
    "CUST-REF-7781"
  ],
  "requiredPickupDate": "2024-12-24T12:00:00Z",
  "requiredDeliveryBy": "2024-12-26T12:00:00Z",
  "appointments": {
    "pickup": {
      "channel": "PORTAL",
      "portalUrl": "https://retaillink.example.com/scheduling",
      "contacts": [
        {
          "name": "Maria Lopez",
          "email": "maria@aqua.com",
          "phone": "+15555550101",
          "role": "Warehouse Manager"
        }
      ],
      "instructions": "Driver must check in at gate B. Lift gate required. Schedule via portal at least 24 hours in advance.",
      "referenceNumbers": [
        "81CRR",
        "DOCK-12"
      ],
      "leadTimeHours": 24
    },
    "delivery": {
      "channel": "PORTAL",
      "portalUrl": "https://retaillink.example.com/scheduling",
      "contacts": [
        {
          "name": "Maria Lopez",
          "email": "maria@aqua.com",
          "phone": "+15555550101",
          "role": "Warehouse Manager"
        }
      ],
      "instructions": "Driver must check in at gate B. Lift gate required. Schedule via portal at least 24 hours in advance.",
      "referenceNumbers": [
        "81CRR",
        "DOCK-12"
      ],
      "leadTimeHours": 24
    }
  },
  "shipperDispatch": {
    "name": "Acme Logistics",
    "email": "dispatch@example.com",
    "phone": "+15555550100",
    "scac": "ACME"
  }
}

Response

Shipment created successfully

idstring

Unique identifier for the order

companyIdstring

Company ID that owns this order

userIdstring

User ID who created this order

orderNumberstring

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

totalPriceInCentsinteger

Total price of the order in cents (USD)

createdAtstring date-time

Time when the order was created (ISO 8601 format)

updatedAtstring date-time

Time when the order was last updated (ISO 8601 format)

Example response

{
  "id": "67b6c5fcfbf1be6b24127646",
  "companyId": "67c0dfa95bff090747660465",
  "userId": "679410f5b074882a64b9ea7f",
  "orderNumber": "ZKYQ5",
  "orderStatus": "CONFIRMED",
  "totalPriceInCents": 125000,
  "createdAt": "2025-02-20T17:31:10.430Z",
  "updatedAt": "2025-02-27T22:51:49.865Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.