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

# Book a shipment

> Books a shipment with the carrier. This transmits the shipment data electronically and generates tracking numbers and shipping documents. Supports asynchronous processing via the Prefer header.



## OpenAPI

````yaml /openapi-v2beta.json post /team/{team}/shipments/{shipment}/booking
openapi: 3.1.0
info:
  title: Smart Send API
  description: >-
    Unified API for shipping operations including service points, routing, and
    rates.


    ## Localization


    The API performs language negotiation to determine the most suitable
    language for translatable content (such as service names, tracking
    descriptions, and error messages). The negotiation considers:


    1. The `Accept-Language` request header (if provided)

    2. The team's configured default language

    3. English as the ultimate fallback


    The resolved language is used for all translatable strings in the response.


    ## Idempotency

    Write operations support **idempotency keys** so you can safely retry a
    request after a network error, timeout, or uncertain outcome without risking
    a duplicate side effect such as booking the same shipment twice.


    Idempotency is opt-in: include an `Idempotency-Key` header on a write
    request (`POST` or `DELETE`) to enable it. Requests sent without the header
    are not deduplicated. The key is a client-generated string of 16–128
    characters (letters, digits, `.`, `_`, `-`) and is compared as-is, so it is
    case-sensitive.


    When a key is reused with an identical payload within 24 hours, the API
    returns the original response (status code and body) without re-executing
    the operation and sets the `Idempotency-Replayed: true` response header.
    Reusing a key with a different payload returns `422 Unprocessable Entity`.
    If the original request is still being processed, the retry returns `409
    Conflict` with a `Retry-After` header indicating when to try again. Keys are
    scoped per client and expire automatically after the 24-hour window.


    See the [idempotency
    guide](https://docs.smartsend.io/api-reference/idempotency) for requirements
    and examples.


    ## User-Agent

    We recommend including a descriptive `User-Agent` header with every request,
    following the `Product/Version (Comments)` pattern from [RFC
    7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.3). A good
    User-Agent helps us identify your integration and speeds up debugging when
    you contact support.


    Example: `smart-send-logistics/8.1.0 (WooCommerce/8.5.0; WordPress/6.4.2;
    PHP/8.1)`


    ## Request-ID

    We recommend including a unique `Request-ID` header with every request. The
    value is echoed back in the response and included in internal logs, making
    it possible to correlate logs from your implementation with logs in Smart
    Send. This is especially useful when contacting support about a specific
    request.
  version: 2.0.0-beta
  contact:
    name: Smart Send
    url: https://www.smartsend.io
servers:
  - url: https://app.smartsend.io/api/v2
    description: Production
security:
  - bearerAuth: []
  - oauth2: []
tags:
  - name: Teams
    description: Teams available to the authenticated user
  - name: Service Points
    description: Pickup points and delivery locations
  - name: Routing
    description: Reference data (carriers, services, addons) and route availability
  - name: Rates
    description: Shipping rates and pricing for specific shipments
  - name: Tracking
    description: Shipment tracking information and event history
  - name: Shipments
    description: Create and manage shipments
  - name: Booking
    description: Booking of shipments
    externalDocs:
      description: Booking documentation
      url: https://docs.smartsend.io/features/booking
  - name: Booking batches
    description: |-
      Batch operations for booking multiple shipments asynchronously.

      <Note>Processing operates after the _first-in-first-out_ principle.</Note>
    externalDocs:
      description: Batch booking documentation
      url: https://docs.smartsend.io/features/booking#batch-booking
paths:
  /team/{team}/shipments/{shipment}/booking:
    post:
      tags:
        - Booking
      summary: Book a shipment
      description: >-
        Books a shipment with the carrier. This transmits the shipment data
        electronically and generates tracking numbers and shipping documents.
        Supports asynchronous processing via the Prefer header.
      operationId: createBooking
      parameters:
        - $ref: '#/components/parameters/team'
        - $ref: '#/components/parameters/Accept-Language'
        - $ref: '#/components/parameters/Request-ID'
        - $ref: '#/components/parameters/Idempotency-Key'
        - $ref: '#/components/parameters/Prefer'
        - name: shipment
          in: path
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
          description: Unique identifier of the shipment to book
      responses:
        '200':
          description: Shipment booked successfully
          headers:
            Correlation-ID:
              $ref: '#/components/headers/Correlation-ID'
            Request-ID:
              $ref: '#/components/headers/Request-ID'
            Idempotency-Replayed:
              $ref: '#/components/headers/Idempotency-Replayed'
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Shipment'
          links:
            GetTrackingByNumber:
              operationId: getTracking
              parameters:
                trackingNumber: $response.body#/data/parcels/0/tracking_code
              description: >-
                The `tracking_code` from each parcel can be used as the
                `trackingNumber` parameter during tracking
        '202':
          $ref: '#/components/responses/Accepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerAuth: []
        - oauth2:
            - shipment:write
components:
  parameters:
    team:
      name: team
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        examples:
          - ad9546c1-393e-49a5-9a72-5cc146c9bec5
      description: Team identifier. All resources are scoped to this team.
    Accept-Language:
      name: Accept-Language
      in: header
      required: false
      schema:
        type: string
        default: en
        examples:
          - da-DK, da;q=0.9, en;q=0.8
      description: >-
        Preferred language(s) for translatable content using BCP 47 language
        tags. Supports quality values (q-factors) for priority ordering. The API
        negotiates the best available language based on this header, the team's
        configured language, and available translations. If omitted, the team's
        default language is used.
    Request-ID:
      name: Request-ID
      in: header
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 128
        pattern: ^[A-Za-z0-9._-]{1,128}$
      description: >-
        Any value passed in this request will be returned in the same header.
        This can be used to correlate requests between client and server.
      examples:
        uuid:
          summary: UUID v4
          value: 3f5d9a8e-8e6f-4d9b-9d9c-9c6b3db2d1a0
        opaque:
          summary: Opaque client-generated key
          value: booking-12345-at-1768609378
    Idempotency-Key:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional key that makes a write request idempotent so it can be safely
        retried. Reusing the key with an identical payload within 24 hours
        returns the original response without re-executing the operation (with
        an `Idempotency-Replayed: true` response header); reusing it with a
        different payload returns 422, and retrying while the original is still
        processing returns 409 with a `Retry-After` header. Use a
        client-generated, case-sensitive string of 16–128 characters (letters,
        digits, `.`, `_`, `-`). Deriving it deterministically from the request —
        for example the order ID combined with a hash of the payload — lets
        retries reuse the same key without storing it. See
        https://docs.smartsend.io/api-reference/idempotency.
      schema:
        type: string
        minLength: 16
        maxLength: 128
        pattern: ^[A-Za-z0-9._-]{16,128}$
      examples:
        uuid:
          summary: UUID v4
          value: 3f5d9a8e-8e6f-4d9b-9d9c-9c6b3db2d1a0
        derived:
          summary: Deterministic key derived from the request
          value: >-
            order-4521_9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
    Prefer:
      name: Prefer
      in: header
      required: false
      schema:
        type: string
        enum:
          - respond-async
      description: >-
        Set to 'respond-async' to request asynchronous processing. When set, the
        API returns 202 Accepted with an Operation object for polling instead of
        waiting for completion.
  headers:
    Correlation-ID:
      description: >-
        Unique identifier for the request, useful for debugging and support. The
        id is automatically assigned to each request and can helps trace the
        request in system logs. Provide this value in case of any errors helps
        debugging.
      schema:
        type: string
        format: uuid
        examples:
          - 550e8400-e29b-41d4-a716-446655440000
    Request-ID:
      description: >-
        If the request contained a `Request-ID` then the same value is returned
        as the `Request-ID`. This can be used to correlate requests between
        client and server.
      schema:
        type: string
    Idempotency-Replayed:
      description: >-
        Present and set to `true` when the response is a replay of an earlier
        request with the same `Idempotency-Key`, rather than a newly executed
        operation.
      schema:
        type: boolean
        examples:
          - true
    Retry-After:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
        examples:
          - 30
  schemas:
    Shipment:
      type: object
      required:
        - uuid
        - state
        - currency
        - weight_unit
        - dimension_unit
        - invoice_number
        - reference
        - identifier
        - uri
        - delivery
        - parties
        - parcels
        - total_net_amount
        - tax_amount
        - duty_amount
        - shipping_net_amount
        - shipping_tax_amount
        - created_at
        - booked_at
      description: A shipment for booking
      properties:
        uuid:
          type:
            - 'null'
            - string
          format: uuid
          readOnly: true
          description: Unique identifier for the shipment
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
        state:
          readOnly: true
          description: Current state of the shipment
          anyOf:
            - type: 'null'
            - allOf:
                - $ref: '#/components/schemas/ShipmentState'
        currency:
          type: string
          minLength: 3
          maxLength: 3
          description: ISO 4217 currency code for all monetary values
          examples:
            - EUR
        weight_unit:
          description: Unit for all weight values in this shipment
          anyOf:
            - type: 'null'
            - allOf:
                - $ref: '#/components/schemas/WeightUnit'
        dimension_unit:
          description: Unit for all dimension values in this shipment
          anyOf:
            - type: 'null'
            - allOf:
                - $ref: '#/components/schemas/DimensionUnit'
        invoice_number:
          type:
            - 'null'
            - string
          description: Invoice or order number
          examples:
            - INV-1001121
        reference:
          type:
            - 'null'
            - string
          description: Human-readable reference visible externally
          examples:
            - Order-5521
        identifier:
          type:
            - 'null'
            - string
          description: System identifier for internal integrations
        uri:
          type:
            - 'null'
            - string
          format: uri
          description: >-
            URI linking to the source of this shipment (webshop order URL, deep
            link, or any URI scheme)
        delivery:
          $ref: '#/components/schemas/DeliveryInfo'
        parties:
          $ref: '#/components/schemas/ShipmentParties'
        parcels:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ShipmentParcel'
          description: Parcels in this shipment
        total_net_amount:
          type:
            - 'null'
            - integer
          description: Total goods value in minor units (cents) excluding tax
          examples:
            - 15920
        tax_amount:
          type:
            - 'null'
            - integer
          description: Total goods tax in minor units (cents)
          examples:
            - 3980
        duty_amount:
          type:
            - 'null'
            - integer
          description: Total goods duty in minor units (cents)
          examples:
            - 5572
        shipping_net_amount:
          type:
            - 'null'
            - integer
          description: Shipping cost in minor units (cents) excluding tax
          examples:
            - 3920
        shipping_tax_amount:
          type:
            - 'null'
            - integer
          description: Shipping tax in minor units (cents)
          examples:
            - 980
        created_at:
          type:
            - 'null'
            - string
          format: date-time
          readOnly: true
          description: When the shipment was created
        booked_at:
          type:
            - 'null'
            - string
          format: date-time
          readOnly: true
          description: When the shipment was booked with the carrier
    ShipmentState:
      type: string
      description: Current state of the shipment in the booking lifecycle
      enum:
        - open
        - queued
        - booked
        - cancelled
        - failed
    WeightUnit:
      type: string
      description: Unit of measurement for weight
      enum:
        - g
        - kg
        - lb
        - oz
      examples:
        - g
    DimensionUnit:
      type: string
      description: Unit of measurement for dimensions
      enum:
        - mm
        - cm
        - m
        - in
      examples:
        - cm
    DeliveryInfo:
      description: >-
        Shipping service with addons. Used in Shipment requests and responses.
        For requests, provide carrier and service. For responses, carrier_code,
        service_code and other details are populated.
      allOf:
        - $ref: '#/components/schemas/DeliveryInfoBase'
        - type: object
          properties:
            carrier:
              type:
                - 'null'
                - string
              writeOnly: true
              description: Carrier code for booking
              examples:
                - postnord
            service:
              type:
                - 'null'
                - string
              writeOnly: true
              description: Service code for booking
              examples:
                - postnord_agent
            incoterm:
              type:
                - 'null'
                - string
              enum:
                - EXW
                - FCA
                - CPT
                - CIP
                - DAP
                - DPU
                - DDP
                - FAS
                - FOB
                - CFR
                - CIF
              description: Incoterms 2020 delivery terms code
              examples:
                - DAP
          required:
            - carrier
            - service
            - incoterm
    ShipmentParties:
      type: object
      required:
        - receiver
        - pickup
      description: Parties involved in the shipment
      properties:
        receiver:
          $ref: '#/components/schemas/ReceiverParty'
        pickup:
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/PickupParty'
    ShipmentParcel:
      type: object
      description: A parcel within a shipment
      properties:
        uuid:
          type:
            - 'null'
            - string
          format: uuid
          readOnly: true
          description: Unique identifier for the parcel
        reference:
          type:
            - 'null'
            - string
          description: Human-readable reference for the parcel
        identifier:
          type:
            - 'null'
            - string
          description: System identifier for internal integrations
        tracking_code:
          type:
            - 'null'
            - string
          readOnly: true
          description: Carrier tracking number (assigned after booking)
          examples:
            - '00340434161094015749'
        tracking_url:
          type:
            - 'null'
            - string
          format: uri
          description: Public URL for tracking this shipment
          examples:
            - https://track.smartsend.io/00340434161094015749
        freetext:
          type:
            - 'null'
            - string
          description: Description or notes for the parcel
          examples:
            - Gift wrapped as per requested
        gross_weight:
          type:
            - 'null'
            - number
          minimum: 0
          description: >-
            Weight of the parcel including both packaging and content (in the
            shipment's weight_unit)
          examples:
            - 1500
        length:
          type:
            - 'null'
            - number
          minimum: 0
          description: Parcel length (in the shipment's dimension_unit)
          examples:
            - 30
        width:
          type:
            - 'null'
            - number
          minimum: 0
          description: Parcel width (in the shipment's dimension_unit)
          examples:
            - 20
        height:
          type:
            - 'null'
            - number
          minimum: 0
          description: Parcel height (in the shipment's dimension_unit)
          examples:
            - 15
        total_net_amount:
          type:
            - 'null'
            - integer
          description: Total value in minor units (cents) excluding tax
          examples:
            - 15920
        tax_amount:
          type:
            - 'null'
            - integer
          description: Tax amount in minor units (cents)
          examples:
            - 3980
        duty_amount:
          type:
            - 'null'
            - integer
          description: Duty amount in minor units (cents)
          examples:
            - 5572
        items:
          type:
            - 'null'
            - array
          items:
            $ref: '#/components/schemas/ShipmentParcelItem'
          description: Items contained in this parcel
        documents:
          type:
            - 'null'
            - array
          readOnly: true
          items:
            $ref: '#/components/schemas/ShipmentDocument'
          description: Documents associated with this parcel (labels, etc.)
      required:
        - uuid
        - reference
        - identifier
        - tracking_code
        - tracking_url
        - freetext
        - gross_weight
        - length
        - width
        - height
        - total_net_amount
        - tax_amount
        - duty_amount
        - items
        - documents
    Operation:
      type: object
      description: Represents an asynchronous operation that can be polled for status
      required:
        - uuid
        - state
        - resource_type
        - resource_uuid
        - created_at
        - started_at
        - finished_at
        - error
      properties:
        uuid:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for this operation
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
        state:
          $ref: '#/components/schemas/OperationState'
        resource_type:
          type:
            - 'null'
            - string
          readOnly: true
          description: Type of resource being operated on
          examples:
            - shipment
        resource_uuid:
          type:
            - 'null'
            - string
          format: uuid
          readOnly: true
          description: UUID of the resource being operated on
          examples:
            - 550e8400-e29b-41d4-a716-446655440001
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: When the operation was created
        started_at:
          type:
            - 'null'
            - string
          format: date-time
          readOnly: true
          description: When the operation started processing
        finished_at:
          type:
            - 'null'
            - string
          format: date-time
          readOnly: true
          description: When the operation completed (success or failure)
        error:
          type:
            - 'null'
            - object
          readOnly: true
          description: Error details if the operation failed
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
    ErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error message
          examples:
            - Something unexpected happened.
    ValidationErrorResponse:
      type: object
      required:
        - message
        - errors
      properties:
        message:
          type: string
          description: Human-readable error message summarizing the validation failure
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Object containing field names as keys and arrays of error messages
            as values
      examples:
        - message: The given data was invalid.
          errors:
            field_name:
              - The field name is required.
    RateLimitErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error message indicating rate limit exceeded
    DeliveryInfoBase:
      type: object
      description: Base shipping service information with carrier details and addons.
      properties:
        carrier_code:
          type:
            - 'null'
            - string
          description: Carrier code
          readOnly: true
          examples:
            - postnord
        carrier_name:
          type:
            - 'null'
            - string
          description: Human-readable carrier name
          readOnly: true
          examples:
            - PostNord
        carrier_logo_url:
          type:
            - 'null'
            - string
          format: uri
          description: URL to the carrier's logo image
          readOnly: true
        carrier_icon_url:
          type:
            - 'null'
            - string
          format: uri
          description: URL to the carrier's icon image
          readOnly: true
        service_code:
          type:
            - 'null'
            - string
          description: Full service code (carrier_code + '_' + service suffix)
          readOnly: true
          examples:
            - postnord_agent
        service_name:
          type:
            - 'null'
            - string
          description: Localized human-readable service name
          readOnly: true
          examples:
            - Pickup Point
        is_pickup:
          type:
            - 'null'
            - boolean
          description: Whether this service delivers to pickup points
          readOnly: true
        is_return:
          type:
            - 'null'
            - boolean
          description: Whether this is a return service
          readOnly: true
        addons:
          type:
            - 'null'
            - array
          items:
            $ref: '#/components/schemas/Addon'
          description: Available or selected addons
      required:
        - carrier_code
        - carrier_name
        - carrier_logo_url
        - carrier_icon_url
        - service_code
        - service_name
        - is_pickup
        - is_return
        - addons
    ReceiverParty:
      type: object
      required:
        - reference
        - identifier
        - uri
        - address
        - contact
        - identifiers
      description: Receiver/recipient party details
      properties:
        reference:
          type:
            - 'null'
            - string
          description: Human-readable reference visible to the recipient
        identifier:
          type:
            - 'null'
            - string
          description: System identifier for internal integrations
        uri:
          type:
            - 'null'
            - string
          format: uri
          description: URI linking to this party (URL, deep link, or any URI scheme)
        address:
          $ref: '#/components/schemas/Address'
        contact:
          $ref: '#/components/schemas/Contact'
        identifiers:
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/PartyIdentifiers'
    PickupParty:
      type: object
      required:
        - service_point_code
        - company
        - address
        - reference
        - identifier
        - uri
      description: Pickup point/service point for delivery
      properties:
        service_point_code:
          type: string
          description: >-
            Carrier's service point code (agent number) used to book delivery to
            this location
          examples:
            - '12345'
        company:
          type:
            - 'null'
            - string
          readOnly: true
          description: Name of the pickup point location
          examples:
            - Netto Nørrebrogade
        address:
          readOnly: true
          description: Address of the pickup point (populated after booking)
          anyOf:
            - type: 'null'
            - allOf:
                - $ref: '#/components/schemas/Address'
        reference:
          type:
            - 'null'
            - string
          description: Human-readable reference for the pickup point
        identifier:
          type:
            - 'null'
            - string
          description: System identifier for internal integrations
        uri:
          type:
            - 'null'
            - string
          format: uri
          description: URI linking to this pickup point (URL, deep link, or any URI scheme)
    ShipmentParcelItem:
      type: object
      description: Individual item within a parcel
      properties:
        reference:
          type:
            - 'null'
            - string
          description: Human-readable reference for the item
        identifier:
          type:
            - 'null'
            - string
          description: System identifier for internal integrations
        uri:
          type:
            - 'null'
            - string
          format: uri
          description: >-
            URI linking to this item (product page URL, deep link, or any URI
            scheme)
        image_url:
          type:
            - 'null'
            - string
          format: url
          description: URL for an product thumbnail image
          examples:
            - https://www.example.com/products/1234-image1.jpeg
        sku:
          type:
            - 'null'
            - string
          description: Stock keeping unit identifier
          examples:
            - PROD-001
        location:
          type:
            - 'null'
            - string
          description: Warehouse location
          examples:
            - AA-01-B45-C
        name:
          type:
            - 'null'
            - string
          description: Product name
          examples:
            - Widget
        description:
          type:
            - 'null'
            - string
          description: Product description for customs
        tariff_code:
          type:
            - 'null'
            - string
          description: HS/customs tariff code
          examples:
            - '8471300000'
        country_of_origin:
          type:
            - 'null'
            - string
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2 country code of origin
          examples:
            - CN
        quantity:
          type:
            - 'null'
            - number
          minimum: 0
          description: Quantity of this item
          examples:
            - 2
        total_net_amount:
          type:
            - 'null'
            - integer
          description: Total value for all quantities in minor units (cents) excluding tax
          examples:
            - 15920
        tax_amount:
          type:
            - 'null'
            - integer
          description: Total tax for all quantities in minor units (cents)
          examples:
            - 3980
        duty_amount:
          type:
            - 'null'
            - integer
          description: Total duty for all quantities in minor units (cents)
          examples:
            - 5572
        net_weight:
          type:
            - 'null'
            - number
          minimum: 0
          description: >-
            Weight of all items excluding any packaging (in the shipment's
            weight_unit)
          examples:
            - 550
        cost_amount:
          type:
            - 'null'
            - integer
          description: Cost of all itemst in minor units (cents) - no vat or duty
          examples:
            - 5300
      required:
        - reference
        - identifier
        - uri
        - image_url
        - sku
        - location
        - name
        - description
        - tariff_code
        - country_of_origin
        - quantity
        - total_net_amount
        - tax_amount
        - duty_amount
        - net_weight
        - cost_amount
    ShipmentDocument:
      type: object
      required:
        - type
        - format
        - url
      description: Document associated with a parcel (label, customs form, etc.)
      properties:
        type:
          type: string
          enum:
            - label
            - customs_declaration
            - commercial_invoice
            - packing_list
          description: Type of document
        format:
          type: string
          enum:
            - pdf
            - zpl
            - png
          description: File format of the document
        url:
          type: string
          format: uri
          description: URL to download the document
    OperationState:
      type: string
      description: Current state of an asynchronous operation
      enum:
        - pending
        - processing
        - completed
        - failed
    Addon:
      type: object
      required:
        - code
        - name
      properties:
        code:
          type: string
          description: Addon code (SCREAMING_SNAKE_CASE)
          examples:
            - SIGNATURE
        name:
          type: string
          description: Localized human-readable addon name
          readOnly: true
          examples:
            - Signature
    Address:
      type: object
      required:
        - address_lines
        - postal_code
        - city
        - country
        - administrative_area
      properties:
        address_lines:
          type:
            - 'null'
            - array
          items:
            type: string
          maxItems: 3
          description: Street address lines (e.g., street name, building, floor)
          examples:
            - - 3200 Whitehaven St. NW
              - Building A, Floor 2
        postal_code:
          type:
            - 'null'
            - string
          description: Postal/ZIP code
          examples:
            - '20008'
        city:
          type: string
          description: City
          examples:
            - Washington
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2 country code
          examples:
            - US
        administrative_area:
          type:
            - 'null'
            - string
          minLength: 2
          maxLength: 3
          description: >-
            The sub-national subdivision code (e.g., state, province, or
            department) representing the suffix part of the ISO 3166-2 standard.
            This field should contain only the characters following the hyphen.
            For example, for 'US-NY', provide 'NY'; for 'JP-13', provide '13'
          examples:
            - DC
    Contact:
      type: object
      required:
        - name_lines
        - company
        - email
        - phone
      description: Contact information for a party
      properties:
        name_lines:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 2
          description: Name lines (e.g., person name, company name, department)
          examples:
            - - John Doe
              - Att. Finance department
        company:
          type:
            - 'null'
            - string
          description: Company or organization name
          examples:
            - Acme Corp
        email:
          type:
            - 'null'
            - string
          format: email
          description: Email address
          examples:
            - john@example.com
        phone:
          type:
            - 'null'
            - string
          description: Phone number with country code
          examples:
            - '+4512345678'
    PartyIdentifiers:
      type: object
      description: Tax and trade identifiers for customs clearance
      properties:
        vat:
          type:
            - 'null'
            - string
          description: VAT identification number
          examples:
            - DK12345678
        eori:
          type:
            - 'null'
            - string
          description: Economic Operators Registration and Identification number (EU)
          examples:
            - DK1234567890123
        gb_eori:
          type:
            - 'null'
            - string
          description: GB EORI number for UK customs
          examples:
            - GB123456789000
        tax_id:
          type:
            - 'null'
            - string
          description: Tax identification number
          examples:
            - DK1234567890
        voec:
          type:
            - 'null'
            - string
          description: VOEC (VAT on E-Commerce) number for Norway
          examples:
            - '2000123'
      required:
        - vat
        - eori
        - gb_eori
        - tax_id
        - voec
  responses:
    Accepted:
      description: Request accepted for asynchronous processing
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID'
        Request-ID:
          $ref: '#/components/headers/Request-ID'
        Location:
          description: URL to poll for operation status
          schema:
            type: string
            format: uri
      content:
        application/json:
          schema:
            type: object
            required:
              - data
            properties:
              data:
                $ref: '#/components/schemas/Operation'
    Unauthorized:
      description: Authentication credentials were missing or invalid
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID'
        Request-ID:
          $ref: '#/components/headers/Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The authenticated user does not have permission to perform this action
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID'
        Request-ID:
          $ref: '#/components/headers/Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID'
        Request-ID:
          $ref: '#/components/headers/Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: >-
        A request with the same `Idempotency-Key` is still being processed. Wait
        for the duration in the `Retry-After` header, then retry. See
        https://docs.smartsend.io/api-reference/idempotency.
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID'
        Request-ID:
          $ref: '#/components/headers/Request-ID'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: The request data failed validation
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID'
        Request-ID:
          $ref: '#/components/headers/Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded. Wait before retrying.
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID'
        Request-ID:
          $ref: '#/components/headers/Request-ID'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorResponse'
    InternalServerError:
      description: An unexpected error occurred on the server
      headers:
        Correlation-ID:
          $ref: '#/components/headers/Correlation-ID'
        Request-ID:
          $ref: '#/components/headers/Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: The service is temporarily unavailable. Please try again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      description: OAuth 2.0 Authorization Code flow for API access
      flows:
        authorizationCode:
          authorizationUrl: https://app.smartsend.io/oauth/authorize
          tokenUrl: https://app.smartsend.io/oauth/token
          scopes:
            service_points: Access service points and pickup locations
            routing: Access routing information (carriers, services, addons, routes)
            tracking:read: Access shipment tracking information
            rates:read: Get shipping rates and pricing
            shipment:read: Read shipment information
            shipment:write: Create and manage shipments

````