--- updatedAt: 2026-06-01T20:21:38.000Z agentTools: projectIndex: https://docs.shipoway.com/llms.txt --- # Confirm shipment pickup Confirm that the shipment has been picked up. Transitions the order to IN_TRANSIT status. **Required fields:** `pickupTime` is required. All other fields (location, coordinates, signedBy, notes) are optional but recommended. **State requirement:** The shipment must be in ACCEPTED status. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Oway Carrier API", "description": "Carrier integration API for managing offers, shipments, bundles, documents, and coverage data. All responses use snake_case field naming.", "contact": { "name": "Oway Support", "email": "support@oway.io" }, "version": "1.0.0" }, "externalDocs": { "description": "Oway API Developer Portal", "url": "https://oway.readme.io" }, "servers": [ { "url": "https://api.oway.io", "description": "Production" }, { "url": "https://api.sandbox.oway.io", "description": "Sandbox Environment" } ], "security": [ { "bearerAuth": [], "apiKey": [] } ], "tags": [ { "name": "Carrier API", "description": "Carrier integration endpoints for managing offers, shipments, bundles, documents, and coverage data.\n\n**Authentication & Authorization Required:**\n\nAll endpoints require BOTH credentials:\n1. **Bearer Token** (`authorization: Bearer {token}`) - Proves identity, requires `carrier` scope\n2. **API Key** (`x-oway-api-key: oway_ck_...`) - Determines which carrier's resources you can access\n\nThe API key is tied to your carrier company and automatically scopes all operations to that company's data.\n" } ], "paths": { "/v1/carrier/shipments/{identifier}/pickup": { "put": { "tags": [ "Carrier API" ], "summary": "Confirm shipment pickup", "description": "Confirm that the shipment has been picked up. Transitions the order to IN_TRANSIT status.\n\n**Required fields:** `pickupTime` is required. All other fields (location, coordinates, signedBy, notes) are optional but recommended.\n\n**State requirement:** The shipment must be in ACCEPTED status.", "operationId": "confirmPickup", "parameters": [ { "name": "identifier", "in": "path", "description": "Shipment identifier (offerId, orderNumber, or carrierReference)", "required": true, "schema": { "type": "string" }, "example": "Y73Q0" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickupConfirmationRequest" } } }, "required": true }, "responses": { "200": { "description": "Pickup confirmed, order status updated to PICKED_UP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierShipment" } } } }, "400": { "description": "Invalid request: pickupTime is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "401": { "description": "Unauthorized: missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "403": { "description": "Forbidden: missing/invalid API key or API access not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "409": { "description": "Shipment not in valid state for pickup confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } } } } } }, "components": { "schemas": { "EventCoordinates": { "type": "object", "description": "GPS coordinates for a shipment event", "properties": { "latitude": { "type": "number", "format": "double", "description": "Latitude in decimal degrees", "example": 33.7701, "maximum": 90, "minimum": -90 }, "longitude": { "type": "number", "format": "double", "description": "Longitude in decimal degrees", "example": -118.1937, "maximum": 180, "minimum": -180 } } }, "EventLocation": { "type": "object", "description": "Location where a shipment event occurred", "properties": { "address1": { "type": "string", "description": "Primary street address", "example": "1531 Junipero Avenue" }, "address2": { "type": "string", "description": "Secondary address line (suite, unit, etc.)", "example": "Dock 5" }, "city": { "type": "string", "description": "City name", "example": "Long Beach" }, "state": { "type": "string", "description": "Two-letter state abbreviation", "example": "CA" }, "zip_code": { "type": "string", "description": "5-digit ZIP code", "example": "90804" }, "country": { "type": "string", "description": "Country code", "example": "US" } } }, "PickupConfirmationRequest": { "type": "object", "description": "Request body for confirming shipment pickup", "properties": { "pickup_time": { "type": "string", "format": "date-time", "description": "Time the shipment was picked up" }, "location": { "$ref": "#/components/schemas/EventLocation", "description": "Location where the pickup occurred" }, "coordinates": { "$ref": "#/components/schemas/EventCoordinates", "description": "GPS coordinates of the pickup location" }, "driver_name": { "type": "string", "description": "Name of the driver who performed the pickup", "maxLength": 255, "minLength": 0 }, "signed_by": { "type": "string", "description": "Name of the person who signed at pickup", "maxLength": 255, "minLength": 0 }, "notes": { "type": "string", "description": "Additional notes about the pickup", "maxLength": 1000, "minLength": 0 } }, "required": [ "pickup_time" ] }, "CarrierAddress": { "type": "object", "description": "Address information for pickup or delivery locations", "properties": { "name": { "type": "string", "description": "Name of the location or business", "example": "Fairgrounds Distribution Center" }, "address1": { "type": "string", "description": "Primary street address", "example": "1531 Junipero Avenue" }, "address2": { "type": "string", "description": "Secondary address line (suite, unit, etc.)", "example": "Dock 5" }, "city": { "type": "string", "description": "City name", "example": "Long Beach" }, "state": { "type": "string", "description": "Two-letter state abbreviation", "example": "CA", "pattern": "[A-Z]{2}" }, "zip_code": { "type": "string", "description": "5-digit ZIP code", "example": "90804", "pattern": "\\d{5}" }, "phone_number": { "type": "string", "description": "Contact phone number in E.164 format", "example": "+18087857650", "pattern": "^\\+[1-9]\\d{1,14}$" }, "contact_person": { "type": "string", "description": "Name of the contact person at this location", "example": "Mike Johnson" }, "open_time": { "type": "string", "description": "Opening time for the location in 24-hour format (HH:mm). Defaults to 10:00 if not provided.", "example": "10:00", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "close_time": { "type": "string", "description": "Closing time for the location in 24-hour format (HH:mm). Defaults to 16:00 if not provided.", "example": "16:00", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "notes": { "type": "string", "description": "Additional notes or instructions for the driver", "example": "Dock 3, enter from back of building" }, "liftgate_required": { "type": "boolean", "description": "Whether a liftgate is required at this location", "example": false }, "limited_access": { "type": "boolean", "description": "Whether this is a limited access location (residential, construction site, etc.)", "example": false }, "appointment_required": { "type": "boolean", "description": "Whether an appointment is required for pickup/delivery", "example": true }, "lumper_required": { "type": "boolean", "description": "Third-party labor handles loading/unloading at this stop; the driver does not handle freight.", "example": false }, "inside_required": { "type": "boolean", "description": "Freight must be brought inside the facility rather than left at the dock.", "example": false } }, "required": [ "address1", "city", "contact_person", "name", "phone_number", "state", "zip_code" ] }, "CarrierComponent": { "type": "object", "description": "Individual pallet/component details", "properties": { "pallet_count": { "type": "integer", "format": "int32", "description": "Number of pallets in this component", "example": 1 }, "pounds_weight": { "type": "number", "format": "float", "description": "Weight in pounds for this component", "example": 600 }, "pallet_dimensions": { "type": "array", "description": "Pallet dimensions [length, width, height] in inches", "example": [ 48, 40, 60 ], "items": { "type": "number" } }, "freight_class": { "type": "string", "description": "Freight class code", "example": "70" } } }, "CarrierShipment": { "type": "object", "description": "Carrier shipment details (post-acceptance)", "properties": { "id": { "type": "string", "description": "Unique offer identifier", "example": "507f1f77bcf86cd799439012" }, "status": { "type": "string", "description": "Current offer/shipment status", "enum": [ "PENDING", "ACCEPTED", "PICKED_UP", "DELIVERED", "REJECTED", "EXPIRED", "CANCELLED" ], "enumDescriptions": { "CANCELLED": "Shipment was cancelled", "DELIVERED": "Shipment delivered to destination", "ACCEPTED": "Carrier has accepted the offer and is scheduled for pickup", "EXPIRED": "Offer expired before carrier responded", "PICKED_UP": "Shipment picked up and in transit to delivery", "PENDING": "Offer sent to carrier, awaiting acceptance or rejection", "REJECTED": "Carrier rejected the offer" } }, "carrier_reference": { "type": "string", "description": "Carrier's own tracking reference number", "example": "CARRIER-TRK-789" }, "rejection_reason": { "type": "string", "description": "Reason for rejection (populated when status is REJECTED)" }, "rejection_reason_text": { "type": "string", "description": "Free-text explanation for rejection" }, "order": { "$ref": "#/components/schemas/Order", "description": "Order details" }, "pickup": { "$ref": "#/components/schemas/CarrierAddress", "description": "Pickup location address and contact" }, "delivery": { "$ref": "#/components/schemas/CarrierAddress", "description": "Delivery location address and contact" }, "tracking": { "$ref": "#/components/schemas/CarrierTracking", "description": "Estimated and actual pickup/delivery dates (populated after acceptance)" }, "payout": { "$ref": "#/components/schemas/Payout", "description": "Carrier payout information" }, "currency": { "type": "string", "description": "ISO 4217 currency code for payout amounts", "example": "USD" }, "assigned_driver": { "$ref": "#/components/schemas/Driver", "description": "Assigned driver and vehicle information" }, "pickup_confirmation": { "$ref": "#/components/schemas/PickupConfirmation", "description": "Pickup confirmation details (populated after pickup)" }, "delivery_confirmation": { "$ref": "#/components/schemas/DeliveryConfirmation", "description": "Delivery confirmation details (populated after delivery)" }, "pickup_pin": { "type": "string", "description": "PIN code for pickup verification", "example": "1234" }, "delivery_pin": { "type": "string", "description": "PIN code for delivery verification", "example": "5678" }, "deadline": { "type": "string", "format": "date-time", "description": "Offer expiration time — must accept or reject before this time", "example": "2026-01-15T12:00:00Z" }, "created_at": { "type": "string", "format": "date-time", "description": "When this offer was created", "example": "2026-01-15T08:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When this offer was last updated", "example": "2026-01-15T10:30:00Z" } } }, "CarrierTracking": { "type": "object", "description": "Shipment tracking information", "properties": { "order_number": { "type": "string", "description": "Human-readable PRO number for the shipment (5-character alphanumeric)", "example": "ZKYQ5" }, "order_status": { "type": "string", "description": "Current status of the order", "enum": [ "INITIALIZED", "CONFIRMED", "ACCEPTED", "ASSIGNED", "PICKED_UP", "IN_TRANSIT", "DELIVERED", "CANCELLED", "REJECTED" ], "example": "PICKED_UP", "enumDescriptions": { "CANCELLED": "Shipment cancelled", "DELIVERED": "Shipment delivered to destination", "ACCEPTED": "Carrier has accepted the shipment", "INITIALIZED": "Shipment created but not yet confirmed for pickup", "CONFIRMED": "Shipment confirmed and awaiting carrier assignment", "IN_TRANSIT": "Freight in transit (alias for PICKED_UP)", "ASSIGNED": "Driver assigned and scheduled for pickup", "PICKED_UP": "Freight picked up and in transit", "REJECTED": "Shipment will not be carried — either declined by the shipper or dropped after no coverage was secured in time" } }, "actual_pickup_date": { "type": "string", "format": "date-time", "description": "Actual pickup date/time (ISO 8601 format)", "example": "2024-12-23T10:30:00Z" }, "actual_delivery_date": { "type": "string", "format": "date-time", "description": "Actual delivery date/time (ISO 8601 format)", "example": "2024-12-25T14:00:00Z" }, "estimated_pickup_date": { "type": "string", "format": "date-time", "description": "Estimated pickup date/time (ISO 8601 format)", "example": "2024-12-23T09:00:00Z" }, "estimated_delivery_date": { "type": "string", "format": "date-time", "description": "Estimated delivery date/time (ISO 8601 format)", "example": "2024-12-25T12:00:00Z" } } }, "DeliveryConfirmation": { "type": "object", "description": "Carrier-reported delivery confirmation details", "properties": { "delivery_time": { "type": "string", "format": "date-time", "description": "Actual delivery time", "example": "2026-01-15T14:30:00Z" }, "address": { "type": "string", "description": "Formatted delivery address", "example": "456 Market St, Oakland, CA 94607" }, "latitude": { "type": "number", "format": "double", "description": "GPS latitude at delivery", "example": 37.7749 }, "longitude": { "type": "number", "format": "double", "description": "GPS longitude at delivery", "example": -122.4194 }, "signed_by": { "type": "string", "description": "Name of person who received the shipment", "example": "Recipient Name" }, "signature_image_url": { "type": "string", "description": "URL to signature image", "example": "https://storage.oway.io/signatures/sig-12345.png" }, "proof_of_delivery_url": { "type": "string", "description": "URL to proof of delivery document", "example": "https://storage.oway.io/pod/pod-12345.pdf" }, "notes": { "type": "string", "description": "Additional notes about the delivery", "example": "Delivered to front desk" }, "recorded_at": { "type": "string", "format": "date-time", "description": "When this confirmation was recorded", "example": "2026-01-15T14:35:00Z" } } }, "Driver": { "type": "object", "description": "Assigned driver information", "properties": { "name": { "type": "string", "description": "Driver's full name", "example": "John Smith" }, "phone": { "type": "string", "description": "Driver's phone number in E.164 format (e.g., +15551234567)", "example": "+15551234567" }, "vehicle_id": { "type": "string", "description": "Vehicle identifier assigned to this shipment", "example": "TRUCK-42" } } }, "Order": { "type": "object", "description": "Order details visible to the carrier", "properties": { "order_number": { "type": "string", "description": "Human-readable PRO number for the shipment (5-character alphanumeric)", "example": "Y73Q0" }, "order_status": { "type": "string", "description": "Current status of the order", "enum": [ "INITIALIZED", "CONFIRMED", "ACCEPTED", "ASSIGNED", "PICKED_UP", "IN_TRANSIT", "DELIVERED", "CANCELLED", "REJECTED" ], "example": "CONFIRMED", "enumDescriptions": { "CANCELLED": "Shipment cancelled", "DELIVERED": "Shipment delivered to destination", "ACCEPTED": "Carrier has accepted the shipment", "INITIALIZED": "Shipment created but not yet confirmed for pickup", "CONFIRMED": "Shipment confirmed and awaiting carrier assignment", "IN_TRANSIT": "Freight in transit (alias for PICKED_UP)", "ASSIGNED": "Driver assigned and scheduled for pickup", "PICKED_UP": "Freight picked up and in transit", "REJECTED": "Shipment will not be carried — either declined by the shipper or dropped after no coverage was secured in time" } }, "description": { "type": "string", "description": "Cargo description", "example": "Electronics - 2 pallets shrink-wrapped" }, "total_pallet_count": { "type": "integer", "format": "int32", "description": "Total number of pallets", "example": 2 }, "total_pounds_weight": { "type": "number", "format": "float", "description": "Total weight in pounds", "example": 1200 }, "po_number": { "type": "string", "description": "Shipper's purchase order number", "example": "PO-2026-4521" }, "ref_number": { "type": "string", "description": "Shipper's reference number", "example": "REF-8834" }, "components": { "type": "array", "description": "Individual pallet/component details", "items": { "$ref": "#/components/schemas/CarrierComponent" } }, "created_at": { "type": "string", "format": "date-time", "description": "When the order was created", "example": "2026-01-15T08:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the order was last updated", "example": "2026-01-15T10:30:00Z" } } }, "Payout": { "type": "object", "description": "Carrier payout information", "properties": { "total_in_cents": { "type": "integer", "format": "int64", "description": "Total payout amount in cents (USD). Includes base payout plus all additional charges.", "example": 125000 } } }, "PickupConfirmation": { "type": "object", "description": "Carrier-reported pickup confirmation details", "properties": { "pickup_time": { "type": "string", "format": "date-time", "description": "Actual pickup time", "example": "2026-01-15T10:30:00Z" }, "address": { "type": "string", "description": "Formatted pickup address", "example": "123 Main St, San Francisco, CA 94102" }, "latitude": { "type": "number", "format": "double", "description": "GPS latitude at pickup", "example": 37.7749 }, "longitude": { "type": "number", "format": "double", "description": "GPS longitude at pickup", "example": -122.4194 }, "driver_name": { "type": "string", "description": "Name of driver who picked up", "example": "John Smith" }, "signed_by": { "type": "string", "description": "Name of person who handed over the shipment", "example": "Jane Doe" }, "notes": { "type": "string", "description": "Additional notes about the pickup", "example": "Picked up from dock 3" }, "recorded_at": { "type": "string", "format": "date-time", "description": "When this confirmation was recorded", "example": "2026-01-15T10:35:00Z" } } }, "ProblemDetail": { "type": "object", "description": "RFC 9457 Problem Details error response", "properties": { "type": { "type": "string", "description": "A URI reference that identifies the problem type", "example": "https://api.oway.io/errors/location-not-serviceable" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type", "example": "Bad Request" }, "status": { "type": "integer", "format": "int32", "description": "The HTTP status code", "example": 400 }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem", "example": "pickupAddress.zipCode must be a 5-digit ZIP code" }, "reason": { "type": "string", "description": "A machine-readable reason code for programmatic handling", "example": "pickup_not_covered" }, "violations": { "type": "array", "description": "Per-field validation failures when a request is rejected for one or more invalid fields. Present only on validation-style errors.", "items": { "$ref": "#/components/schemas/Violation" } } } }, "Violation": { "type": "object", "description": "A single field-level validation failure.", "properties": { "field": { "type": "string", "description": "Field path that failed validation", "example": "orderComponents[0].dimensions" }, "entity": { "type": "string", "description": "Entity the failing field belongs to (e.g. pickupAddress, deliveryAddress, appointment). Lets clients disambiguate otherwise-identical field paths across stops. Nullable for violations that have no entity context.", "example": "deliveryAddress" }, "reason": { "type": "string", "description": "Human-readable reason the field is invalid. Any dimension or weight ceiling quoted in the message is configuration-driven, so treat the figures in the example as indicative rather than as a fixed part of the contract. The example is one rejection rather than every one: it shows a shipment that requested no liftgate. A shipment whose pickup or delivery requires a liftgate is measured against a different, generally tighter, set of dimension ceilings, and its message quotes whichever figures applied.", "example": "Component dimensions of 110x48x40 are invalid (pallets must be less than 96x96x108, and greater than 1x1x1)" } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "description": "**Authorization** - API key that determines which company's resources you can access.\n\nEach API key is tied to a **single company** in Oway. Use the appropriate key type:\n\n| Key Type | Format | Use For |\n|----------|--------|---------|\n| Shipper | `oway_sk_xxx...` | Shipper API (`/v1/shipper/**`) |\n| Carrier | `oway_ck_xxx...` | Carrier API (`/v1/carrier/**`) |\n\nGenerate keys in your Oway portal (Settings → API Keys).\n\n**Required** alongside Bearer token for external API access.", "name": "x-oway-api-key", "in": "header", "x-default": "oway_sk_your_api_key_here" }, "bearerAuth": { "type": "http", "description": "**Authentication** - Bearer token that proves your identity.\n\nObtain from `/v1/auth/token` endpoint. Tokens are valid for 24 hours.\n\nRequired scopes:\n- `shipper` for Shipper API\n- `carrier` for Carrier API\n- `dev` or `prod` for environment access\n\n**Required** alongside API key for external API access.", "scheme": "bearer", "bearerFormat": "JWT", "x-default": "your_bearer_token_here" } } }, "x-readme": { "headers": [ { "value": "Bearer your_bearer_token_here", "key": "authorization" }, { "value": "oway_sk_your_api_key_here", "key": "x-oway-api-key" } ], "explorer-enabled": true, "samples-languages": [ "go", "typescript", "java", "php", "python" ] } } ```