# Create a service

Create a new service for a shipment.

## What happens

- Service is created for the specified shipment
- Vendor is associated with the service
- Charges are recorded

## Note

Services are typically created as part of shipment creation.
Use this endpoint to add additional services to an existing shipment.

Endpoint: POST /services
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `shipmentId` (string, required)
    Parent shipment ID

  - `service` (object, required)

  - `service.vendor` (any, required)

  - `service.vendorContact` (any)

  - `service.serviceType` (string, required)
    Type of service.
- DRAYAGE: Port/rail drayage
- CUSTOMS_CLEARANCE: Customs brokerage
- WAREHOUSING: Warehouse storage
- CROSS_DOCK: Cross-dock handling
- TRANSLOAD: Transloading service
- FUMIGATION: Cargo fumigation
- INSPECTION: Cargo inspection
- DOCUMENTATION: Documentation handling
- INSURANCE: Cargo insurance
- CARGO_HANDLING: General cargo handling
- OTHER: Other service type
    Enum: "DRAYAGE", "CUSTOMS_CLEARANCE", "WAREHOUSING", "CROSS_DOCK", "TRANSLOAD", "FUMIGATION", "INSPECTION", "DOCUMENTATION", "INSURANCE", "CARGO_HANDLING", "OTHER"

  - `service.description` (string)

  - `service.charges` (array)

  - `service.charges.chargeCode` (any, required)

  - `service.charges.amount` (number, required)

  - `service.charges.quantity` (number)

  - `service.scheduledDate` (string)

  - `service.referenceNumber` (string)

## Response 201 fields (application/json):

  - `id` (string, required)
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `key` (string,null)
    Human-readable service ID
    Example: "SVC-12345"

  - `shipmentId` (string)
    Parent shipment

  - `shipmentKey` (string,null)
    Parent shipment friendly ID

  - `vendor` (object)
    Enhanced reference to a vendor profile.
Includes full vendor details in addition to id/key.

  - `vendor.id` (string, required)
    Vendor UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `vendor.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-VENDOR-ABC-001"

  - `vendor.friendlyId` (string, required)
    Human-readable vendor identifier
    Example: "V123456"

  - `vendor.name` (string, required)
    Vendor legal name
    Example: "ABC Warehouse Services"

  - `vendor.email` (string,null)
    Primary email address
    Example: "billing@abcwarehouse.com"

  - `vendor.phone` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `vendor.status` (string,null)
    Vendor status
    Example: "ACTIVE"

  - `vendor.currency` (string,null)
    Preferred currency code (ISO 4217)
    Example: "USD"

  - `vendor.createdAt` (string, required)
    When the vendor was created
    Example: "2025-01-15T10:00:00Z"

  - `vendor.updatedAt` (string, required)
    When the vendor was last updated
    Example: "2025-01-15T14:30:00Z"

  - `vendorContact` (object)

  - `vendorContact.name` (string)

  - `vendorContact.phone` (string,null)

  - `vendorContact.email` (string,null)

  - `serviceType` (string)
    Type of service.
- DRAYAGE: Port/rail drayage
- CUSTOMS_CLEARANCE: Customs brokerage
- WAREHOUSING: Warehouse storage
- CROSS_DOCK: Cross-dock handling
- TRANSLOAD: Transloading service
- FUMIGATION: Cargo fumigation
- INSPECTION: Cargo inspection
- DOCUMENTATION: Documentation handling
- INSURANCE: Cargo insurance
- CARGO_HANDLING: General cargo handling
- OTHER: Other service type
    Enum: "DRAYAGE", "CUSTOMS_CLEARANCE", "WAREHOUSING", "CROSS_DOCK", "TRANSLOAD", "FUMIGATION", "INSPECTION", "DOCUMENTATION", "INSURANCE", "CARGO_HANDLING", "OTHER"

  - `status` (string, required)
    Current status of the service.

Active states:
- ACTIVE: Service is active/in progress

Billing states (AP):
- AWAITING_INVOICE: Waiting for vendor invoice
- INVOICE_IN_REVIEW: Invoice received, under review
- APPROVED_TO_PAY: Approved for payment
- PAID: Paid to vendor

Final states:
- CANCELED: Service canceled
    Enum: "ACTIVE", "AWAITING_INVOICE", "INVOICE_IN_REVIEW", "APPROVED_TO_PAY", "PAID", "CANCELED"

  - `description` (string,null)
    Service description

  - `charges` (array)
    Flattened charges array

  - `charges.chargeCode` (object)
    Reference to another resource (returned in responses)

  - `charges.chargeCode.id` (string, required)
    Resource UUID

  - `charges.description` (string,null)

  - `charges.amount` (number)

  - `charges.quantity` (number)

  - `totalCost` (number,null)
    Sum of all charges

  - `scheduledDate` (string,null)

  - `completedDate` (string,null)

  - `referenceNumber` (string,null)
    Vendor reference number

  - `createdAt` (string, required)

  - `updatedAt` (string,null)

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message