> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.ovrsea.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a shipment

> Creates a shipment for the account between locations or ports.



## OpenAPI

````yaml /openapi.json post /v1/shipments
openapi: 3.1.0
info:
  title: OVRSEA API
  version: 1.3.2
servers:
  - url: https://api.cf.ovrsea.com
security: []
paths:
  /v1/shipments:
    post:
      tags:
        - Shipments
      summary: Create a shipment
      description: Creates a shipment for the account between locations or ports.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                cargo:
                  properties:
                    containers:
                      description: >-
                        Containers of a full container load, one line per
                        container type. Required when `load_type` is `fcl`.
                      items:
                        properties:
                          container_type:
                            type: string
                            enum:
                              - twenty_foot_standard
                              - twenty_foot_reefer
                              - twenty_foot_flat_rack
                              - twenty_foot_open_top
                              - forty_foot_standard
                              - forty_foot_reefer
                              - forty_foot_flat_rack
                              - forty_foot_open_top
                              - forty_foot_highcube_standard
                              - forty_foot_highcube_reefer
                              - forty_foot_highcube_flat_rack
                              - forty_foot_highcube_open_top
                              - forty_five_foot_highcube_standard
                          count:
                            description: Number of containers of this type.
                            example: 2
                            maximum: 100
                            minimum: 1
                            type: integer
                        required:
                          - container_type
                          - count
                        type: object
                      maxItems: 13
                      type: array
                    loads:
                      description: >-
                        Package lines of a less than container load. Required
                        when `load_type` is `lcl`.
                      items:
                        properties:
                          count:
                            description: Number of packages of the line.
                            example: 4
                            minimum: 1
                            type: integer
                          package_type:
                            description: >-
                              `colis` is a carton, `palletized_80_120` and
                              `palletized_100_120` are pallets of that footprint
                              in centimetres, `palletized_specific` is a pallet
                              of another footprint, `solid_box` is a rigid crate
                              and `vrac` is bulk.
                            enum:
                              - colis
                              - palletized_80_120
                              - palletized_100_120
                              - palletized_specific
                              - solid_box
                              - vrac
                            type: string
                          total_volume:
                            description: Volume of the whole line, in cubic `volume_unit`.
                            example: 3840000
                            type: number
                          total_weight:
                            description: Weight of the whole line, in `weight_unit`.
                            example: 1200
                            type: number
                          volume_unit:
                            enum:
                              - cm
                              - in
                            type: string
                          weight_unit:
                            enum:
                              - kg
                              - lbs
                            type: string
                        required:
                          - package_type
                          - volume_unit
                          - weight_unit
                        type: object
                      type: array
                  type: object
                cargo_ready_date:
                  example: '2027-03-01'
                  format: date
                  type: string
                desired_delivery_date:
                  example: '2027-04-15'
                  format: date
                  type: string
                freight_mode:
                  enum:
                    - air
                    - ocean
                    - rail
                  type: string
                incoterm:
                  type: string
                  enum:
                    - exw
                    - fca
                    - fas
                    - fob
                    - cpt
                    - cfr
                    - cif
                    - cip
                    - dap
                    - ddp
                    - dpu
                    - dat
                  example: fob
                load_type:
                  description: >-
                    `fcl` cargo is described by `cargo.containers`, `lcl` cargo
                    by `cargo.loads`.
                  enum:
                    - fcl
                    - lcl
                  type: string
                name:
                  type: string
                  example: June Air Export USA
                needs_ad_valorem_insurance:
                  type: boolean
                route:
                  description: >-
                    Needs an origin, the pickup location or the departure port,
                    and a destination, the arrival port or the delivery
                    location.
                  properties:
                    delivery_location_id:
                      description: Id of a location returned by `/v1/locations`.
                      example: '45'
                      pattern: ^[0-9]{1,18}$
                      type: string
                    delivery_port_id:
                      description: >-
                        Id of the arrival port, as returned by
                        `/v1/ports/{locode}` for the same `freight_mode`.
                      example: '2'
                      pattern: ^[0-9]{1,18}$
                      type: string
                    pickup_location_id:
                      description: Id of a location returned by `/v1/locations`.
                      example: '23'
                      pattern: ^[0-9]{1,18}$
                      type: string
                    pickup_port_id:
                      description: >-
                        Id of the departure port, as returned by
                        `/v1/ports/{locode}` for the same `freight_mode`.
                      example: '1'
                      pattern: ^[0-9]{1,18}$
                      type: string
                  type: object
                specific_instructions:
                  example: Call the warehouse before delivery
                  type: string
                transported_goods:
                  properties:
                    goods_description:
                      example: Ceramic tiles
                      type: string
                  type: object
              required:
                - freight_mode
                - load_type
                - needs_ad_valorem_insurance
                - route
              type: object
        required: true
      responses:
        '201':
          description: The created shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '400':
          description: A required field is missing or a field is invalid.
          content:
            application/json:
              schema:
                description: A required field is missing or a field is invalid.
                type: string
        '429':
          description: >-
            The account reached its shipment and quote request creation limit.
            The `Retry-After` header gives the number of seconds to wait.
          content:
            application/json:
              schema:
                description: >-
                  The account reached its shipment and quote request creation
                  limit. The `Retry-After` header gives the number of seconds to
                  wait.
                type: string
components:
  schemas:
    Shipment:
      type: object
      modelName: Shipment
      tag:
        - Shipments
      properties:
        name:
          type: string
          example: June Air Export USA
        ovrsea_shipment_id:
          type: string
          example: CDEF
        status:
          type: string
          enum:
            - booking_request
            - awaiting_booking
            - booked
            - draft
            - in_progress
            - finished
            - cancelled
        created_at:
          $ref: '#/components/schemas/DateWithTime'
        incoterm:
          type: string
          enum:
            - exw
            - fca
            - fas
            - fob
            - cpt
            - cfr
            - cif
            - cip
            - dap
            - ddp
            - dpu
            - dat
          example: fob
        freight_mode:
          type: string
          enum:
            - air
            - ocean
            - rail
            - truck
        load_type:
          type: string
          enum:
            - fcl
            - lcl
            - both
        freight_type:
          type: string
          enum:
            - port_to_door
            - door_to_port
            - door_to_door
            - port_to_port
        route:
          type: object
          properties:
            pickup_location_id:
              type: string
              example: '23'
            origin_port_unlocode:
              type: string
              example: FR/FOS
            destination_port_unlocode:
              type: string
              example: US/NYC
            delivery_location_id:
              type: string
              example: '45'
        cargo_ready_date:
          $ref: '#/components/schemas/SimpleDate'
        desired_delivery_date:
          $ref: '#/components/schemas/SimpleDate'
        specific_instructions:
          type: string
          description: Optional field containing specific instruction given by the client
        cargo:
          type: object
          properties:
            total_weight:
              $ref: '#/components/schemas/Weight'
            total_volume:
              $ref: '#/components/schemas/Volume'
            total_teus:
              type: integer
              description: Shipment total of Twenty-Equivalent Units
              example: 5
            containers:
              type: array
              items:
                $ref: '#/components/schemas/Container'
            loads:
              type: array
              items:
                $ref: '#/components/schemas/Load'
        transported_goods:
          type: object
          properties:
            goods_description:
              type: string
              example: Description of the shipped goods
            is_stackable:
              type: boolean
              default: true
            is_hazardous:
              type: boolean
              default: false
            hazardous_description:
              type: string
              example: UN1993
            contains_lithium:
              type: boolean
              default: false
            lithium_packaging_type:
              type: string
              enum:
                - alone
                - contained
                - packed
            contains_magnets:
              type: boolean
              default: false
            needs_controlled_temperature:
              type: boolean
              default: false
            temperature_range_description:
              type: string
              example: 5-25°C
        commercial_value:
          $ref: '#/components/schemas/Price'
        needs_ad_valorem_insurance:
          type: boolean
          default: false
        purchase_order_references:
          type: array
          items:
            type: string
            example: 4500346155
        main_tracking_dates:
          type: object
          properties:
            pickup_date:
              $ref: '#/components/schemas/TrackingDate'
            departure_date:
              $ref: '#/components/schemas/TrackingDate'
            arrival_date:
              $ref: '#/components/schemas/TrackingDate'
            delivery_date:
              $ref: '#/components/schemas/TrackingDate'
        booking_information:
          type: object
          properties:
            carrier:
              type: string
              example: CMA CGM
            master_bill:
              type: string
              example: LHV1190703558
            house_bill:
              type: string
              example: HOUSEREF12357
            ocean_booking:
              type: object
              properties:
                booking_number:
                  type: string
                  example: TWLEH2106004
                voyage:
                  type: string
                  example: 033E
                vessel:
                  type: string
                  example: CMA CGM Jacques Saadé
            air_booking:
              type: object
              properties:
                flight_number:
                  type: string
                  example: AF256
                chargeable_weight:
                  $ref: '#/components/schemas/Weight'
        invoice_status:
          type: string
          enum:
            - available
            - awaiting_invoice
            - due
            - paid
            - partially_paid
        invoice_references:
          type: array
          items:
            type: string
            example: FAC2022-9567
        accepted_quote:
          type: object
          properties:
            id:
              type: string
              example: '325'
            request_date:
              $ref: '#/components/schemas/DateWithTime'
            accepted_date:
              $ref: '#/components/schemas/DateWithTime'
    DateWithTime:
      modelName: DateWithTime
      type: string
      example: '2021-09-20T10:02:09+01:00'
    SimpleDate:
      modelName: SimpleDate
      type: string
      example: '2021-10-11'
    Weight:
      modelName: Weight
      type: object
      description: Weight
      properties:
        value:
          type: number
          format: float
          example: 350.25
        unit:
          type: string
          enum:
            - kg
            - lbs
          example: kg
    Volume:
      modelName: Volume
      type: object
      description: Unit volume in cbm
      properties:
        value:
          type: number
          format: float
          example: 10.25
        unit:
          type: string
          example: cbm
    Container:
      type: object
      modelName: Container
      properties:
        container_type:
          type: string
          enum:
            - twenty_foot_standard
            - twenty_foot_reefer
            - twenty_foot_flat_rack
            - twenty_foot_open_top
            - forty_foot_standard
            - forty_foot_reefer
            - forty_foot_flat_rack
            - forty_foot_open_top
            - forty_foot_highcube_standard
            - forty_foot_highcube_reefer
            - forty_foot_highcube_flat_rack
            - forty_foot_highcube_open_top
            - forty_five_foot_highcube_standard
        container_number:
          type: string
          example: TEMU8667058
        seal_number:
          type: string
          example: 1332641
        purchase_order_references:
          type: array
          items:
            type: string
            example: 4500346155
    Load:
      type: object
      modelName: Load
      properties:
        count:
          type: number
          example: 3
        type:
          type: string
          enum:
            - pallet
            - package
            - rigid_crate
          format: LoadType
        weight:
          $ref: '#/components/schemas/Weight'
        volume_unit:
          type: string
          example: cm
          description: (deprecated)
        length:
          $ref: '#/components/schemas/Size'
        width:
          $ref: '#/components/schemas/Size'
        height:
          $ref: '#/components/schemas/Size'
    Price:
      modelName: Price
      type: object
      properties:
        amount:
          type: number
          format: float
          example: 150357.99
        currency:
          type: string
          enum:
            - AED
            - AUD
            - BHD
            - BRL
            - CAD
            - CHF
            - CNY
            - DKK
            - EUR
            - GBP
            - HKD
            - IDR
            - INR
            - JPY
            - MXN
            - KRW
            - KWD
            - MYR
            - NOK
            - NZD
            - PLN
            - SEK
            - SGD
            - THB
            - TND
            - TWD
            - USD
            - XOF
            - XPF
            - ZAR
          example: USD
    TrackingDate:
      modelName: TrackingDate
      type: object
      properties:
        date:
          $ref: '#/components/schemas/DateWithTime'
        status:
          type: string
          enum:
            - estimated
            - actual
            - planned
            - problem
    Size:
      type: object
      modelName: Size
      description: Size
      properties:
        value:
          type: number
          format: float
          example: 10.25
        unit:
          type: string
          enum:
            - cm
            - in
          example: cm

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.