---
title: "Create a service"
method: POST
path: "/services"
tags: ["Services"]
---

# Create a service

`POST /services`

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.

## Request body

- object
  - `shipmentId` string, uuid, required — Parent shipment ID
  - `service` ServiceInput, required
    - `vendor` union, required — Reference to another resource by either ID or client key (used in create/update requests)
      - object
        - `id` string, uuid, required — Resource UUID
        - `key` string — Client-defined reference ID
      - object
        - `id` string, uuid — Resource UUID
        - `key` string, required — Client-defined reference ID
    - `vendorContact` union — Reference to another resource by either ID or client key (used in create/update requests)
      - object
        - `id` string, uuid, required — Resource UUID
        - `key` string — Client-defined reference ID
      - object
        - `id` string, uuid — Resource UUID
        - `key` string, required — Client-defined reference ID
    - `serviceType` 'DRAYAGE' | 'CUSTOMS_CLEARANCE' | 'WAREHOUSING' | 'CROSS_DOCK' | 'TRANSLOAD' | 'FUMIGATION' | 'INSPECTION' | 'DOCUMENTATION' | 'INSURANCE' | 'CARGO_HANDLING' | 'OTHER', 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
    - `description` string
    - `charges` object[]
      - `chargeCode` union, required — Reference to another resource by either ID or client key (used in create/update requests)
        - object
          - `id` string, uuid, required — Resource UUID
          - `key` string — Client-defined reference ID
        - object
          - `id` string, uuid — Resource UUID
          - `key` string, required — Client-defined reference ID
      - `description` string
      - `amount` number, required
      - `quantity` number
    - `scheduledDate` string, date
    - `referenceNumber` string

## Response `201`

Service created successfully

- Service
  - `id` string, uuid, required
  - `key` string, nullable — Human-readable service ID
  - `shipmentId` string, uuid — Parent shipment
  - `shipmentKey` string, nullable — Parent shipment friendly ID
  - `vendor` VendorReference — Enhanced reference to a vendor profile. Includes full vendor details in addition to id/key.
    - `id` string, uuid, required — Vendor UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `friendlyId` string, required — Human-readable vendor identifier
    - `name` string, required — Vendor legal name
    - `email` string, email, nullable — Primary email address
    - `phone` string, nullable — Primary phone number
    - `status` string, nullable — Vendor status
    - `currency` string, nullable — Preferred currency code (ISO 4217)
    - `createdAt` string, date-time, required — When the vendor was created
    - `updatedAt` string, date-time, required — When the vendor was last updated
  - `vendorContact` object
    - `id` string, uuid
    - `name` string
    - `phone` string, nullable
    - `email` string, nullable
  - `serviceType` 'DRAYAGE' | 'CUSTOMS_CLEARANCE' | 'WAREHOUSING' | 'CROSS_DOCK' | 'TRANSLOAD' | 'FUMIGATION' | 'INSPECTION' | 'DOCUMENTATION' | 'INSURANCE' | 'CARGO_HANDLING' | 'OTHER' — 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
  - `status` 'ACTIVE' | 'AWAITING_INVOICE' | 'INVOICE_IN_REVIEW' | 'APPROVED_TO_PAY' | 'PAID' | 'CANCELED', 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
  - `description` string, nullable — Service description
  - `charges` ServiceCharge[] — Flattened charges array
    - `id` string, uuid
    - `chargeCode` ResourceReference — Reference to another resource (returned in responses)
      - `id` string, uuid, required — Resource UUID
      - `key` string, nullable — Client-defined reference ID if set
    - `description` string, nullable
    - `amount` number
    - `quantity` number
  - `totalCost` number, nullable — Sum of all charges
  - `scheduledDate` string, date, nullable
  - `completedDate` string, date, nullable
  - `referenceNumber` string, nullable — Vendor reference number
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, nullable

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `422` — Validation error - invalid field values

---

[API](https://skmtc.net/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.net/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/versions/c44e5e7a4256/schema)